Crystal Shards
By Crystal community
Shards is the official package manager for the Crystal programming language, used to declare, resolve, and install external library dependencies for Crystal projects across development, testing, and continuous integration environments. yml…
Definition
Shards is the official package manager for the Crystal programming language, used to declare, resolve, and install external library dependencies for Crystal projects across development, testing, and continuous integration environments. It reads dependency declarations from a shard.yml file, resolves version constraints against Git repositories, and generates a lock file so builds remain fully reproducible across different machines and team members over time.
Overview
Shards was built alongside Crystal to give the language a package management story from early in its development, following patterns established by mature package managers in other languages such as Ruby's Bundler, which strongly influenced its design given Crystal's Ruby-inspired syntax. Rather than centralizing packages in a single official index, Shards resolves dependencies directly from Git repositories, meaning any publicly or privately hosted Git repository containing a valid shard.yml can serve as a dependency source without requiring registration in a central registry. Mechanically, a Crystal project declares its dependencies in a shard.yml file specifying each dependency's name, source Git URL, and version constraint. Running the install command resolves the dependency graph, clones or updates the required Git repositories at matching tagged versions, and writes a shard.lock file recording the exact resolved versions so that subsequent installs on other machines or CI systems reproduce the same dependency versions deterministically. Because Crystal compiles ahead of time to native binaries, Shards' role is limited to fetching and organizing source dependencies before compilation, rather than managing any runtime module loading. Among package managers for compiled, statically typed languages, Shards' Git-based, registry-free model resembles Go's module system before Go introduced its own module proxy, favoring decentralization over a single curated package index. This contrasts with ecosystems like npm, RubyGems, or Cargo, which centralize packages in official registries; Shards instead relies on discoverability through community-maintained lists and the crystal-lang GitHub organization rather than a hosted package server. In practice, Crystal developers use Shards for essentially every non-trivial project, since the language's standard library, while capable, does not include every utility a web application or CLI tool needs. Popular Crystal web frameworks and CLI libraries are distributed as shards, and most Crystal project tutorials begin by walking through a shard.yml setup. The trade-offs of a Git-based, registry-free approach include slower dependency resolution compared to a centralized index with prebuilt metadata, no built-in vulnerability scanning or download statistics that centralized registries often provide, and a smaller overall ecosystem than package managers backing more widely adopted languages. Because Crystal itself has a comparatively small community relative to mainstream languages, the pool of available shards is also correspondingly smaller, meaning some functionality that would be a simple dependency in a larger ecosystem may need to be written from scratch in Crystal projects. Because Crystal is a comparatively young, small-community language, the number of available shards is smaller than what developers coming from Ruby or JavaScript are used to, so teams sometimes budget extra time to write missing functionality themselves rather than finding an existing shard.
Key Features
- Declares dependencies in a shard.yml file with name, source, and version constraint
- Resolves and fetches dependencies directly from Git repositories
- Generates a shard.lock file for deterministic, reproducible installs
- Requires no central package registry, unlike npm or RubyGems
- Influenced heavily by Ruby's Bundler dependency resolution model
- Supports both public and private Git repositories as dependency sources
- Integrates with Crystal's ahead-of-time compilation workflow
- Allows version constraints using semantic versioning tags on Git repos