Step 1: Install dependencies
There are two components to Sorbet: the command line interface and runtime systems. We’ll declare them in our Gemfile and install them with Bundler:
# -- Gemfile -- gem 'sorbet', :group => :development gem 'sorbet-runtime'
❯ bundle install
This should install cleanly in most Ruby development environments, but see “What platforms does Sorbet support?” in the FAQ for some important caveats.
To test that everything is working so far, we can run these commands:
❯ bundle exec srb [help output] ❯ bundle exec srb typecheck -e 'puts "Hello, world!"' No errors! Great job. ❯ bundle exec ruby -e 'puts(require "sorbet-runtime")' true
Step 2: Initialize Sorbet in our project
For small projects, Sorbet can run on a single file with no additional information. But for projects that have multiple files and depend on other gems, Sorbet needs to know more information to work.
To initialize Sorbet in an existing project, run:
❯ srb init
It’s normal for this command to spew a bunch of output to the terminal. When
it’s done, there should be a
sorbet/ folder in the current directory. Be sure
to check the entire folder into version control.
The contents of the
sorbet/ folder should now look like this:
sorbet/ ├── config └── rbi/ └── ···
sorbet/configis the config file Sorbet will read (see Command Line Reference)
sorbet/rbi/is a folder containing RBI files. RBI files (or “Ruby Interface” files) declare classes, modules, constants, and methods to Sorbet that it can’t see on its own.
srb initcreates many kinds of RBI files. For more information, see RBI files.
If these two items exist, we’re all set to typecheck our project for the first time.
Step 3: Run
srb tc for the first time
Now that we’ve initialized Sorbet, type checking Sorbet should be as simple as:
❯ srb tc
By default, this will type check every Ruby file in the current folder. To configure this, see Command Line Reference.
Step 4: Fix constant resolution errors
At this point, it’s likely that there are lots of errors in our project, but Sorbet silences them by default. Our next job is to unsilence them and then fix the root causes. Empirically, there are a handful of categories of errors people encounter at this step:
Sorbet requires that all files parse as valid Ruby syntax.
Dynamic constant references
Sorbet does not support resolving constants through expressions. For example,
foo.bar::Ais not supported—all constants must be resolvable without knowing what type an expression has. In most cases, it’s possible to rewrite this code to use method calls (like,
Sorbet cannot statically analyze a codebase that dynamically
includes code. For example, code like this is impossible to statically analyze.
Dynamic includes must be rewritten so that all
includes are constant literals.
For Sorbet to be effective, it has to know about every class, module, and constant that’s defined in a codebase, including all gems. Constants are central to understanding the inheritance hierarchy and thus knowing which types can be used in place of which other types.
To solve points (3) and (4), Sorbet uses RBI files. We mentioned RBI
files before when we introduced
srb init. RBI files are purely annotations
files, separate from Ruby source code. While
srb init can automatically create
these files, it’s not a perfect process. To eliminate constant errors, sometimes
Sorbet requires hand-written RBI files.
To learn more about RBI files and how they can help with adopting Sorbet, see the docs here.
Step 5: Enable type checking
At this step, running
srb tc should show zero errors.
Congrats! Step 4 was the biggest hurdle to adopting Sorbet. To recap, Sorbet now enforces that…
all Ruby files parse.
every class, module, and constant in a codebase is known. These can be 100% accurately shown in auto-complete suggestions and used in type annotations.
all gems have explicit interfaces. More than YARD documentation, RBI files are machine-checked documentation about the libraries we’re using.
Importantly, Sorbet does not yet report type errors (the errors we’ve seen so far have been syntax errors and constant resolution errors). The final step is to start enabling more type checks in our code.
The rest of this site is dedicated to learning about the extra checks we can
enable. The tl;dr is that type checking happens when we add
# typed: true to files and write method signatures in
Step 6: Source Control
All files generated by
srb init should be committed to source control,
including the entire
sorbet/rbi/hidden-definitions/errors.txt can be ignored (eg.
.gitignore). It is essentially a debug log for sorbet maintainers and is not
needed at runtime.
See also this explanation of why we commit RBIs.
At this point, Sorbet is currently silencing all type-related errors, and only knows about the types coming from the standard library. Adding type annotations lets Sorbet find more bugs in our code and provide better completion results.
Sorbet relies heavily on runtime type checks to back up the predictions made statically about a codebase. Learn why these checks are necessary, and how to enable them.
Sorbet requires some type annotations in order to work. The most common kind of annotations are method signatures, or
Especially in large codebases, adopting Sorbet benefits from a concerted effort to have the most impact. Tracking metrics is a great way to measure the adoption effort over time, and Sorbet makes collecting them easy.