Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Shards and Web

Shards and Dependencies in Crystal

Learn Crystal's package manager Shards: shard.yml, dependencies, version constraints, shard.lock, install and update, requiring libraries and building a shard, with Ruby stand-ins.

Crystal programs reuse code through shards. A shard is simply a Git repository with a shard.yml file that describes the project. The tool that fetches them is also called shards and ships with the Crystal installer. There is no central package server to publish to: a shard lives in a Git repository, and a directory such as shards.info only indexes them.

The shards tool cannot run on this site and cannot download anything from here, so the listings are read-only. The Ruby stand-ins show how version constraints and a lock file work, by parsing small YAML text in memory.

A new project

Terminal
crystal init app my_app       # an application
crystal init lib my_lib       # a library
cd my_app

crystal init creates shard.yml, src/, spec/, a .gitignore and a license file. The generated shard.yml looks like this:

YAML
name: my_app
version: 0.1.0

authors:
  - Your Name <[email protected]>

targets:
  my_app:
    main: src/my_app.cr

crystal: ">= 1.12.0"

license: MIT

targets names the executables that shards build produces (in bin/). crystal is the version range your code supports.

Declaring dependencies

Add libraries under dependencies (needed to run) or development_dependencies (needed for tests and tooling):

YAML
dependencies:
  kemal:
    github: kemalcr/kemal
    version: ~> 1.5.0
  sqlite3:
    github: crystal-lang/crystal-sqlite3
    version: ">= 0.20.0, < 1.0"
  my_internal:
    git: https://example.com/team/my_internal.git
    branch: main

development_dependencies:
  ameba:
    github: crystal-ameba/ameba

Sources are github:, gitlab:, git: (any URL), path: (a local folder, handy during development) and a few more. You choose a version with version: (a constraint), or pin a branch:, tag: or commit:.

Version constraints

Shards follow semantic versioning: MAJOR.MINOR.PATCH, where a major bump may break your code, a minor adds features, and a patch fixes bugs. The constraints are:

Constraint Meaning
1.2.3 exactly this version
>= 1.2.0 this or newer
~> 1.2.0 at least 1.2.0 but below 1.3.0 (patch updates only)
~> 1.2 at least 1.2 but below 2.0 (minor updates allowed)
>= 1.0, < 2.0 a range

The ~> ("pessimistic") operator is the common choice: it accepts safe updates and stops before a breaking release.

Ruby Ruby stand-in: how ~> works

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

install, update and the lock file

Terminal
shards install     # fetch what shard.lock says (or resolve, if no lock yet)
shards update      # re-resolve, allowing newer versions, rewrite shard.lock
shards list        # show installed shards
shards check       # verify the installed shards match the lock file
shards build       # compile every target to bin/
shards prune       # remove unused packages from lib/

shards install downloads the dependencies into the lib/ folder and writes shard.lock, which records the exact version or commit that was chosen:

YAML
version: 2.0
shards:
  kemal:
    git: https://github.com/kemalcr/kemal.git
    version: 1.5.0
  radix:
    git: https://github.com/luislavena/radix.git
    version: 0.4.1

The lock file is what makes builds repeatable: on another machine, shards install reads the lock and fetches the same versions, even if newer ones exist. Commit shard.lock for applications. For libraries you usually do not commit it, because users resolve their own versions. Add /lib/ and /bin/ to .gitignore.

Ruby Ruby stand-in: resolve versions and write a lock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Using a shard in code

After shards install, require a library by its name (shards in lib/ are on the require path):

CRYSTAL
require "kemal"
require "sqlite3"
require "./helpers/*"       # relative: every file in a folder

get "/" { "Hello" }
Kemal.run

require "name" loads lib/name/src/name.cr. Each shard decides what its main file requires. Requires are processed once per path, so requiring the same library from two files is harmless.

Writing your own shard

A library needs a clear entry file (src/my_lib.cr), a version in shard.yml, and a Git tag per release (git tag v1.0.0). Other projects then depend on it with github: you/my_lib and version: ~> 1.0. Good libraries keep a CHANGELOG, add specs (see Testing with Spec), document with ## comments that crystal docs turns into a website, and follow semver strictly.

flowchart LR
  Y["shard.yml (what you want)"] --> R["shards install / update: resolve"]
  R --> L["shard.lock (what was chosen)"]
  R --> D["lib/ (downloaded sources)"]
  L --> I["shards install elsewhere: same versions"]

shard.yml states wishes; shard.lock records the result.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do shards come from?

    A shard is a Git repository with a shard.yml; the tool clones it.
  2. 2. Which versions does ~> 1.5.0 accept?

    The pessimistic operator allows patch updates only when three numbers are given.
  3. 3. What does shard.lock do?

    shards install follows the lock file; shards update recreates it.
  4. 4. Should an application commit shard.lock?

    Applications commit the lock; libraries usually leave it out so users resolve their own versions.

Summary

  • A shard is a Git repository with shard.yml; the shards tool installs them into lib/.
  • Declare dependencies with github: / git: / path: and a semver version: constraint.
  • ~> accepts safe updates only; shards install follows shard.lock, shards update refreshes it.
  • Use require "name" to load a shard; build targets with shards build.

Next: Building an HTTP Server