Enforcing Modularity in Rails Apps with Packwerk

Summary

Large Rails monoliths can develop high coupling, low cohesion, cross-component calls, shared Active Record models, and classes that know too much because Ruby and Rails provide limited boundary enforcement. Shopify created Packwerk, an open-source static analysis tool that groups Ruby files into packages and enforces dependency and privacy boundaries, including controlled public APIs for constants. It reports the violation type and location with actionable next steps, integrates with CI, and can run locally; installation begins by adding the gem and running packwerk init. Because Ruby static analysis is complex, Packwerk ignores constants that are not autoloaded, reducing false positives at the cost of false negatives. The excerpt says it runs in six Shopify Rails applications, with 48 packages and 30 boundary enforcements in the core codebase, while adoption also prompted work on dependency inversion.

Context

Large Rails applications lacked strong architectural boundaries: Ruby provides limited visibility semantics, Rails offers basic layering, and componentized code could still make cross-component calls or share Active Record models. This contributed to high coupling, low cohesion, difficult changes, spaghetti code, and large classes.

Approach / What changed

Packwerk is a static analysis tool that organizes groups of Ruby files into packages and enforces dependency and privacy boundaries. It surfaces violation types and locations with actionable next steps, supports CI and local checks, and initializes a Rails application through the packwerk init command.

Takeaways

• Packwerk distinguishes dependency boundaries from privacy boundaries, allowing packages to expose selected public constants while restricting private implementation details.
• Packwerk ignores constants that are not autoloaded, a deliberate choice that limits false positives but can produce false negatives in Ruby analysis.
• Packwerk runs in six Shopify Rails applications; the core codebase has 48 packages and 30 boundary enforcements, with checks integrated into CI.

Related reading