---
title: "A Packwerk Retrospective"
description: "Shopify’s retrospective examines Packwerk, a Ruby gem released in September 2020 to enforce package boundaries and help modularize Rails applications. It describes the tool as static analysis that checks constant references against a declared, non-circular dependency graph, with todo files allowing existing violations to be recorded while new ones are blocked. The authors recount how privacy checks shifted attention toward API design, introduced awkward file organization, and were removed in version 3.0. They also explain that Packwerk cannot determine whether package boundaries or violation fixes reflect runtime coupling, so semantic grouping can mislead developers and add harmful indirection. Shopify ultimately treats running code as the strongest progress signal and retains Packwerk mainly to prevent new dependencies at the application’s base layer."
---

# A Packwerk Retrospective

[Shopify](https://yomu.fyi/company/shopify) · 2023-10-18 · Feb 7, 2024

**Type:** Explainer

## Summary

Shopify’s retrospective examines Packwerk, a Ruby gem released in September 2020 to enforce package boundaries and help modularize Rails applications. It describes the tool as static analysis that checks constant references against a declared, non-circular dependency graph, with todo files allowing existing violations to be recorded while new ones are blocked. The authors recount how privacy checks shifted attention toward API design, introduced awkward file organization, and were removed in version 3.0. They also explain that Packwerk cannot determine whether package boundaries or violation fixes reflect runtime coupling, so semantic grouping can mislead developers and add harmful indirection. Shopify ultimately treats running code as the strongest progress signal and retains Packwerk mainly to prevent new dependencies at the application’s base layer.

## Context

Shopify’s team found that defining useful package boundaries and dependency relationships in a large, historically global Rails codebase was difficult. Packwerk could enforce the dependency graph developers specified, but it could not determine whether that graph matched how the code actually ran or whether proposed violation fixes improved the system. Privacy checks also created implementation and API-design problems.

## Approach / What changed

Packwerk defines packages through file directories and a non-circular dependency graph, then statically analyzes constant references for violations. Existing violations can be recorded in package\_todo.yml files while new violations are prevented. Shopify removed privacy checks in version 3.0, adjusted package organization to better reflect actual dependencies, and continued using Packwerk to hold the line against new dependencies at the application’s base layer.

## Takeaways

- Packwerk’s todo files allow teams to record existing dependency violations as a form of declared bankruptcy while preventing new violations from being introduced.
- Privacy checks required app/public directories, encouraged poorly documented public APIs, and shifted attention from dependency relationships to API design; they were removed in Packwerk 3.0.
- Shopify concluded that running code is a better progress signal than an idealized modularity metric, while still using Packwerk to limit new base-layer dependencies.

**Tags:** [Architecture](https://yomu.fyi/topic/architecture), [Monoliths](https://yomu.fyi/topic/monolith), [Refactoring](https://yomu.fyi/topic/refactoring)

- Source: [Shopify](https://shopify.engineering/a-packwerk-retrospective)
- Source URL: https://shopify.engineering/a-packwerk-retrospective
- Ingested by Yomu: 2026-08-30T13:20:36.621Z

[Read original post](https://shopify.engineering/a-packwerk-retrospective)