packwerk

# Packwerk [![Build Status](https://github.com/Shopify/packwerk/workflows/CI/badge.svg)](https://github.com/Shopify/packwerk/actions?query=workflow%3ACI)

> "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)
* Help existing codebases to become more modular without obstructing development

## Prerequisites

Packwerk needs [Zeitwerk](https://github.com/fxn/zeitwerk) enabled, which comes with Rails 6.

Packwerk supports MRI versions 2.7 and above.

## Demo

Watch a [1-minute video demo](https://www.youtube.com/watch?v=NwqlyBAxVpQ&feature=youtu.be) on how Packwerk works.

[![](./static/packwerk-check-demo.png)](https://www.youtube.com/watch?v=NwqlyBAxVpQ&feature=youtu.be)

## Installation

1. Add this line to your application's Gemfile:

```ruby
gem 'packwerk'
```

2. Install the gem

Execute:

    $ bundle install

Or install it yourself as:

    $ gem install packwerk

2. Run `bundle binstub packwerk` to generate the binstub
3. Run `bin/packwerk init` to generate the configuration files

## Usage

Read [USAGE.md](USAGE.md) for usage once Packwerk is installed on your project.

## Pronunciation

"Packwerk" is pronounced [[ˈpakvɛʁk]](https://cdn.shopify.com/s/files/1/0258/7469/files/packwerk.mp3).

## 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/rubyatscale/packwerk-vscode integrates packwerk into Visual Studio Code so you can see violations right in your editor
- https://github.com/vinted/packwerk-intellij integrates packwerk into RubyMine so you can see violations right in your editor
- https://github.com/rubyatscale/packs-rails sets up Rails autoloading, as well as `rspec` and `FactoryBot` integration, for packages arranged in a flat list. packs-rails is quite convenient, but for autoloading we recommend to use `Rails::Engine`s instead.
- https://github.com/rubyatscale/danger-packwerk integrates packwerk with [danger.systems](https://danger.systems) to provide packwerk feedback as Github inline PR comments
- https://github.com/rubyatscale/packwerk-extensions contains extensions for packwerk, including a checker for packwerk that allows you to enforce public API boundaries. This was originally extracted from `packwerk` itself.
- https://github.com/alexevanczuk/packs is a Rust implementation of packwerk that has experimental support for non-Rails, non-Zeitwerk applications.

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can