Boost Dev Experience: Add RBS Signatures

Boost Developer Experience: Implementing RBS Type Signatures for Shakapacker and React on Rails

Hey guys, let's talk about leveling up the developer experience when working with shakapacker and react_on_rails. We're going to dive into how adding RBS (Ruby Signature) type signatures can seriously improve things. Trust me, it's a win-win for everyone involved – from the folks building the gems to the developers using them. So, grab a coffee, and let's get into it.

The Current Pain Points

Right now, both shakapacker and react_on_rails have a common issue: a lack of static type information for their Ruby APIs. What does that mean in practice? Well, it leads to a few headaches, like this:

• IDE Autocomplete Woes: Your IDE, the magical place where you write your code, can't always provide accurate autocomplete or type hints. This makes it harder to discover available methods and understand how to use them.
• Runtime Errors: Type-related errors only pop up at runtime, which means you might not discover them until your code is running and, potentially, breaking. Wouldn't it be great to catch these errors earlier in the development process?
• Documentation Limitations: While we have comments and external documentation, they can be limited. Explicit type information makes APIs much easier to understand.
• Refactoring Risks: Refactoring can become riskier without type checking. Changes might break code without you immediately realizing it.

The Solution: Embracing RBS

The good news is that there's a solution to all these problems: adopting RBS. So, what exactly is RBS? Well, RBS stands for Ruby Signature, and it's Ruby's official type annotation system. It's designed to provide static type information for your Ruby code.

RBS files live in separate .rbs files, usually inside a sig/ directory, which keeps your Ruby code nice and clean, without any inline type annotations. It provides machine-readable type information that tools like Steep or TypeProf can use to perform static type checking. These tools then power IDE features like autocomplete and error detection. It's like having a super-powered spell-checker for your code that helps you catch errors before they even happen. The best part? RBS files don't affect runtime behavior for users who don't use them.

Benefits for Everyone

Benefits for Users

Let's break down the advantages for the developers using shakapacker and react_on_rails:

• Better IDE Support: With RBS, your IDE gets a serious upgrade. You'll get accurate autocomplete, inline type hints, and all sorts of other helpful features that make coding smoother.
• Early Error Detection: The type checker helps you catch errors before your code even runs. It's like having a safety net that prevents runtime crashes.
• Self-Documenting Code: Types are explicit and machine-readable. This creates better documentation than comments.
• Safer Refactoring: Type checking makes refactoring safer. The type checker alerts you to breaking changes, saving you time and headaches.

Benefits for Maintainers

Now, let's explore the advantages for the folks maintaining shakapacker and react_on_rails:

• Clearer Interfaces: Types document what's expected for inputs and outputs, which makes your code much easier to understand and maintain.
• Reduced Bugs: Type mismatches get caught during development. This helps in catching bugs.
• Easier Onboarding: New contributors can understand the APIs faster because the type signatures provide a clear understanding of each method.
• Consistency: Many gems are already adopting RBS. This helps in maintaining consistency.

Proposed Implementation

To make this happen, we'll roll out RBS in phases:

Phase 1: Core Public APIs (Weeks 1-2)

We'll start with the most important parts:

• react_on_rails: We will add signatures for ReactOnRails.configure and configuration classes. Also, we will work with the ReactOnRails::Helper module (e.g., react_component). Plus, we will cover component registration methods.
• shakapacker: This includes Shakapacker.config and configuration classes. Also, the Shakapacker::Helper module. Finally, manifest and compiler interfaces.

Phase 2: Helper Modules & Utilities (Weeks 3-4)

Next up, we'll focus on these areas:

• View helpers and rendering methods.
• Internal utilities with public interfaces.
• Error classes and exceptions.

Phase 3: Internal APIs (Optional, as needed)

Finally, if needed, we'll tackle the following:

• Private methods used across multiple files.
• Complex internal data structures.
• Integration points.

Code Example: See the Transformation

Let's see how RBS will change our code. Here's what it looks like before and after:

Before (No Type Information):

# lib/react_on_rails/helper.rb
def react_component(name, props = {}, options = {})
  # ...
end

After (With RBS):

# lib/react_on_rails/helper.rb (unchanged)
def react_component(name, props = {}, options = {})
  # ...
end

# sig/react_on_rails/helper.rbs (new)
module ReactOnRails
  module Helper
    def react_component: (
      String name,
      ?Hash[untyped, untyped] props,
      ?Hash[Symbol, untyped] options
    ) -> String
  end
end

As you can see, the original code doesn't change. We just add a .rbs file to provide type information.

Implementation Checklist

Here's what we need to do to make this happen:

• [ ] Create sig/ directory structure.
• [ ] Add RBS to development dependencies.
• [ ] Document RBS usage in CONTRIBUTING.md.
• [ ] Start with Phase 1 APIs.
• [ ] Set up type checking in CI (optional, can defer).
• [ ] Add examples to documentation.

Resources to Get You Started

• RBS Documentation: Dive deep into the official RBS documentation at https://github.com/ruby/rbs.
• RBS Guide: Get a comprehensive overview in the RBS Guide at https://rbs.ruby-lang.org/.
• Example: package_json gem: See how the package_json gem is using RBS by visiting https://github.com/shakacode/package_json/tree/main/sig.
• Steep Type Checker: Use Steep to type-check your code: https://github.com/soutaro/steep.

Questions for Discussion

We need to answer these questions:

1. Should we start with shakapacker or react_on_rails first? Let's decide where to begin.
2. Do we want to enable type checking in CI, or just provide signatures? It would be great to have the type checking integrated into our CI processes. However, this is an optional task and can be handled later.
3. Should we include type signatures for internal/private APIs? This is a choice we have to make.

Success Criteria

We'll know we've succeeded when:

• Core public APIs have complete RBS signatures.
• IDE autocomplete works for main methods.
• No negative impact on existing users.
• Documentation is updated to reference type signatures.

Note: This enhancement won't break anything. RBS files are optional and won't affect users who don't use them.