Packwerk Documentation

Packwerk is a Ruby gem designed to enforce boundaries and modularize Rails applications. It allows you to:

• Group files into packages: Define logical boundaries within your codebase.
• Define package-level constant visibility: Control which constants are publicly accessible from outside a package.
• Incremental modularization: Help existing codebases become more modular without obstructing active development.

Core Mental Model: Packwerk performs static analysis on constant references. It does not analyze method calls or objects passed around the application. If you need to analyze method parameters, you should use Sorbet type signatures, as Packwerk understands Sorbet's use of constants for types.

A package is defined by placing a package.yml file in a folder. The package name is the path from the project root to that folder.

You can include arbitrary metadata in package.yml (e.g., for ownership or Slack channels).

Example components/sales/package.yml:

metadata:
  stewards:
  - "@Shopify/sales"
  slack_channels:
  - "#sales"

# components/sales/package.yml
metadata:
  stewards:
  - "@Shopify/sales"
  slack_channels:
  - "#sales"

To prevent new violations from being added to a package's package_todo.yml, use strict mode.

In the package's package.yml, set enforce_dependencies: strict instead of true.

When strict mode is enabled:

1. Running bin/packwerk check will error if any new violations are found.
2. Running bin/packwerk update-todo will return an error instead of adding new violations to the todo file.

Because Ruby is a dynamic language, Packwerk prioritizes avoiding false positives (reporting valid code as a violation) over avoiding false negatives (failing to report an actual violation).

Key Limitations

• Constant Resolution: Packwerk can only resolve references to constants defined via Zeitwerk's autoloader. Code loaded via explicit require that bypasses Zeitwerk conventions may cause issues.
• Scope of Analysis: Packwerk only cares about static constant references. It ignores method calls and object passing. To analyze method parameters, use Sorbet.
• Zeitwerk Configuration: While Packwerk supports custom ActiveSupport inflections, it may produce false positives if you use custom Zeitwerk inflections or directory collapsing directly in your Zeitwerk configuration.

To prevent a package from referencing constants in other packages without explicit permission, enable dependency enforcement in the package's package.yml.

Set enforce_dependencies: true and list the allowed packages under dependencies:.

Example components/shop_identity/package.yml:

enforce_dependencies: true
dependencies:
  - components/platform

In this example, components/shop_identity is prohibited from referencing any constant outside of itself or components/platform.

# components/shop_identity/package.yml
enforce_dependencies: true
dependencies:
  - components/platform

To install Packwerk in your Rails application, add the gem to your Gemfile, install it, generate a binstub, and initialize the configuration files.

Prerequisites

• Zeitwerk: Must be enabled (standard in Rails 6+).
• Ruby: MRI version 2.7 or above.

To avoid waiting for long Continuous Integration (CI) cycles, run Packwerk commands locally on the command line. You can significantly reduce run time by specifying only the specific folders or packages you are working on.

Note: You cannot limit the scope for bin/packwerk validate or bin/packwerk update-todo; these commands always run against the entire application.

bin/packwerk check components/your_package

To get started with Packwerk, first include the gem in your Gemfile. Then, generate a binstub to make the CLI accessible via bin/packwerk:

bundle binstub packwerk

Once the binstub is created, initialize your project to generate the necessary configuration files (packwerk.yml and the root package.yml):

bin/packwerk init

Since Packwerk loads Rails, you can significantly speed up execution by using Spring.

1. Add require 'packwerk/spring_command' to your config/spring.rb file.
2. Run the following command to "springify" your Packwerk binstub:

bin/spring binstub packwerk

When upgrading to Packwerk 2.0, several configuration changes are required to simplify setup:

Move Gem to development group

Packwerk no longer manages application inflections. You should move the packwerk gem from the production group to the development group in your Gemfile.

Remove load_paths from packwerk.yml

The load_paths key in packwerk.yml is no longer used. Packwerk now retrieves load paths directly from Rails. If using Spring, ensure it is properly configured to maintain performance.

Revert to inflections.rb

Packwerk no longer requires a custom inflections.yml file. You should revert to using the standard Rails config/initializers/inflections.rb file using the ActiveSupport::Inflector API.