CR
Shard Architecture Pattern
Crystal shard layout conventions with clear module boundaries, public API design, and shard.yml management
Details
Language / Topic
CrystalCategory
Architecture
Rules
balanced
- Structure a shard with `src/<shard_name>.cr` as the single entry point that `require`s sub-files — never expose internal implementation files as part of the public API.
- Use `module MyShard` as a top-level namespace wrapping all public types — this prevents name collisions when the shard is included in other projects.
- Pin all shard dependencies in `shard.yml` with `version: ~> X.Y` and commit the generated `shard.lock` file for applications — libraries should omit `shard.lock`.
- Use `private` on internal helper methods and `protected` only when subclass access is genuinely needed — keep the public surface of each class minimal and well-documented.