Migrating to Tapioca

Migrating to Tapioca

When adopting types, developers might start by using sorbet-typed, sorbet-rails or other solutions and combinations to get accurate typing information for DSLs and gems. Tapioca aims to provide the complete tooling for generating RBIs for gems and DSLs and does not require being combined with other gems. This document contains the rough steps to migrate to Tapioca.

1. Remove current RBIs
2. Remove other solutions
3. Add Tapioca
4. Run tapioca init
5. Run tapioca dsl (optional)
6. Bump strictness on files

1. Remove current RBIs

Tapioca does not require other solutions to work. Therefore all gem and DSL RBIs should be generated with it and not an alternative solution. The easiest way to adapt is to start over by removing the entire sorbet/rbi folder.

Note: if your application has shims (hand written RBI files), keep them saved somewhere in case you need to restore some of them. Chances are, less shims will be needed after transitioning to Tapioca.

Additionally, don't forget to keep your sorbet/config file too.

If the previously used alternatives had their own configuration files, remove them as well.

2. Remove other solutions

As mentioned, Tapioca is meant to be used on its own. Remove sorbet-rails or other such alternative solutions from the Gemfile.

3. Add Tapioca

Add Tapioca to the Gemfile.

group :development do
  gem "tapioca"
end

And run bundle update.

4. Run tapioca init

This will:

1. Create the configuration file for Sorbet, configuration file for Tapioca and the require.rb file
2. Install the binstub for Tapioca in your app's bin/ folder, so that you can use bin/tapioca to run commands in your app
3. Pull the community RBI annotations from the central repository matching your app's gems
4. Generate the RBIs for your app's gems
5. Generate the RBI file for missing constants

See the Getting started section in Tapioca's README for more details.

5. Run tapioca dsl (optional)

With all the gem RBIs in place, now Tapioca can generate DSL RBIs.

DSL RBIs are definitions that only exist in runtime. For example:

class Post < ApplicationRecord
  # Belongs to will create a few methods in this class
  # to be able to access the associated author. Sorbet
  # does not know about them, since they only exist during
  # runtime. Tapioca can generate the definitions in RBIs
  # for methods like this one.
  belongs_to :author
end

Run bin/tapioca dsl to generate the runtime definitions for your application.

See the Generating RBI files for Rails and other DSLs section in Tapioca's README for more details.

6. Bump strictness on files

After all the RBIs are generated and no type errors are occurring, some files might actually be ready to move from typed: false to typed: true. Spoom can automatically bump files to true if doing so produces no new typing errors.

To bump all possible files to true, simply run bundle exec spoom bump. Read Spoom's documentation for more information: Spoom - Change the sigil used in files

Done! Your application should be all set and type checking should pass.

Things that do not need to happen

Here are some things that do not need to be run for the migration (or ever in some cases).

1. bundle exec srb rbi hidden-definitions: not necessary at all, ever
2. bundle exec srb rbi suggest-typed: not necessary at all, ever. Prefer bundle exec spoom bump