Packwerk

⚠️ While Shopify is actively using `packwerk`, we consider it feature complete.

We are keeping packwerk compatible with current versions of Ruby and Rails, but will accept feature requests only in rare cases. Please submit bug fixes though!

"I know who you are and because of that I know what you do." This knowledge is a dependency that raises the cost of change.

-- Sandi Metz, Practical Object-Oriented Design in Ruby

Packwerk is a Ruby gem used to enforce boundaries and modularize Rails applications.

Packwerk can be used to:

Combine groups of files into packages
Define package-level constant visibility (i.e. have publicly accessible constants)
Enforce privacy (inbound) and dependency (outbound) boundaries between packages
Help existing codebases to become more modular without obstructing development

Prerequisites

Packwerk needs Zeitwerk enabled, which comes with Rails 6.

Packwerk supports MRI versions 2.6 and above.

Demo

Watch a 1-minute video demo on how Packwerk works.

Installation

Add this line to your application's Gemfile:

gem 'packwerk'

Install the gem

Execute:

$ bundle install

Or install it yourself as:

$ gem install packwerk

Run bundle binstub packwerk to generate the binstub
Run bin/packwerk init to generate the configuration files

Usage

Read USAGE.md for usage once Packwerk is installed on your project.

Pronunciation

"Packwerk" is pronounced [ˈpakvɛʁk].

Ecosystem

Various third parties have built tooling on top of packwerk. Here's a selection of some that might prove useful:

https://github.com/bellroy/graphwerk draws a graph of your package dependencies
https://github.com/Gusto/packwerk-vscode integrates packwerk into Visual Studio Code so you can see violations right in your editor
https://github.com/Gusto/stimpack sets up Rails autoloading, as well as rspec and FactoryBot integration, for packages arranged in a flat list. Stimpack is quite convenient, but for autoloading we recommend to use Rails::Engines instead.
https://github.com/rubyatscale/danger-packwerk integrates packwerk with danger.systems to provide packwerk feedback as Github inline PR comments

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Limitations

With Ruby being a very dynamic language, static analysis tools such as Packwerk are bound to have limitations. To reduce the impact of those limitations, Packwerk is designed to avoid false positives (reporting references as violations that are actually fine) at any cost, and we pay the cost by accepting a small number of false negatives (failing to report actual violations).

Packwerk can only resolve references to constants that are defined in code loaded by the application's Zeitwerk autoloader. This is because we rely on Zeitwerk's conventions, and code that is loaded differently (like through an explicit require) often doesn't follow these conventions.
Method calls and objects passed around the application are completely ignored. Packwerk only cares about static constant references. That said, if you want Packwerk to analyze parameters of a method, you can use Sorbet to define a type signature. Sorbet signatures are pure Ruby code and use constants to express types, and Packwerk understands that.
Support for custom Zeitwerk configuration is limited. If custom ActiveSupport inflections are used, Packwerk will understand that and everything is fine. However, if Zeitwerk is directly configured with custom Zeitwerk inflections or to collapse directories, Packwerk will get confused and produce false positives.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/packwerk.

Read and follow the guidelines in CONTRIBUTING.md.

License

The gem is available as open source under the terms of the MIT License.

jeffmeyers/packwerk