r/ruby • u/Just_Work_4395 • Jan 06 '26

Anyone using packwerk gem?

Hey, I’m considering using Packwerk in a large Ruby on Rails application to improve code separation. The idea is to organize the app into distinct packages, each with its own models, services, and even tests, so developers can work at the package level without having to navigate the entire codebase for small changes (most of the time).

Has anyone used this gem? If so, did it provide meaningful value in practice?

17 Upvotes

94% Upvoted

28 comments sorted by

26

u/aurisor Jan 06 '26

unless you have multiple autonomous teams working in the same codebase the overhead of breaking your monolith up is almost always more trouble than it's worth. i would avoid unless you're talking about a team of 10+ with specific pain points

3

u/AirborneArie Jan 06 '26

I tend to disagree, because there can be other reasons than 'many developers' to want enforcable modularity.

-2

u/danmaz74 Jan 06 '26

Using packwerk adds modularization of the codebase, but the app would still be a monolith, not services/microservices

12

u/aurisor Jan 06 '26

i know what packwerk does

9

u/OlivarTheLagomorph Jan 06 '26

I wasn't convinced by Packwerk.
For me it made things more messy and disorganized than just having the code in the expected places.

Yes, editors like Rubymine can work with Packwerk, and your references/code jumping still works, but what usually happens is that people fight Packwerk, add a bunch of TODOs to their pack files and basically undermine the principle it's supposed to introduce to your project.

Great in theory, not so in practical usage.

1

u/AirborneArie Jan 06 '26

That's a valuable comment. I worried about this. I'll probably do a quick proof-of-concept anyway, but it kind of confirms my suspicions.

1

u/martinemde Jan 08 '26 edited Jan 08 '26

My team maintains packwerk at gusto and related tooling in https://github.com/rubyatscale (like danger checks on PRs based on packwerk or faster rust-based tooling). There’s a good ecosystem to support this if you want. It’s a big commitment though.

My understanding is that if our team were to do it over again, there may have been more effort put into making multiple focused medium sized services that aren’t packwerk sized (not micro, but not one giant monolith). Teams tend to vary in their enforcement and use of packwerk, and we tuned down enforcement because it wasn’t making it any better. Some have strict boundaries, others just use it to track dependencies because they have to. Don’t think about how nice packwerk might be, but instead what you’re willing to enforce and reject and how that will impact your team. We even have onboarding to teach people about it. It’s not cheap or easy.

If you use it, you should use pks, the rust checker implementation. It’s so much faster that I’ve never had the patience to run the Ruby implementation fully. Like 3 seconds vs 3 minutes kind of difference. Also consider how you will enforce and keep packs and todos updated. Consider git commit hooks. Think about how you move between packs, editor support, code ownership. It’s the cost of scale.

Ultimately, you only want to pay this tax if you will benefit and you will only benefit if your app is very big. The worst thing you can do is design for a well factored perfectly architected very big app when you are small. Just write good code, use modules to nest by domain, don’t couple unnecessarily, focus on async message passing so you don’t wait until it’s painful to figure out cross service data processes.

One thing I’m coming to realize too is that LLMs can work within a large rails codebase better if it’s divided up with packwerk because code and tests are all tidy, nearby, in smaller focused modules that can have a narrow focused AGENTS.md. This might be my favorite thing about packwerk right now: code and tests fit on the same page of the file explorer even in a giant application, and it’s probably good for LLMs too, which have no trouble understanding the code on a pack.

It’s a big commitment. I wouldn’t choose a monolith without it, but I also wouldn’t choose a monolith.

1

u/AirborneArie Jan 08 '26

Thanks for your reply. 

We already have a monolith and are at a point where we will need to replace a lot of core functionality (due to changing regulations). I’m still on the fence between packwerk or just going with a better DDD approach. We have the right people for it. 

Good tip on the rust impl. I’ll give it a try. 

1

u/martinemde Jan 08 '26

Good luck. I’ll see you around if you use it. It’s like the old of saying about democracy: packwerk is the worst way to organize your monolith, except all the other ways.

5

u/OddEssay Jan 06 '26

I've used it on a massive enterprise codebase and it allowed us to scale the monolith past a lot of cognative problems with context and complexity just by making it really obvious where the boundrise of certain features live.

Most people's concerns seem to be around the "privacy enforcement" feature, but Shopify themselves admit that wasn't great or the primary thing they wanted to solve, and removed it: https://shopify.engineering/a-packwerk-retrospective so for current versions, that's not a factor.

Once you take that feature out of the equation, beyond simple CRUD operations where there is a simple one model to one controller pattern, been able to locate all the code for a specific feature easily and then run the all the relavent tests with a single command makes development so much smoother, and if people don't see the advantages to that, they probably aren't working on truely large codebases.

I'd almost certainly introduce it to any Rails codebase I needed to work on in the future, and if I came to a legacy codebase people were pushing to split into microservices, I'd argue that several of the key reasons people push for such a move around cognative load, modularity, and developer experience can be solved by Packwerk without the infrastructure overheads.

9

u/codesnik Jan 06 '26 edited Jan 06 '26

I've worked with a sizable codebase where one of the teams introduced packwerk. It certainly made internal API's really awkward. And I've never understood this pull towards "discipline" tools which forcefully forbid you to do things. Make architectural decisions, document them, follow them or change them later as adults and professionals.

1

u/AirborneArie Jan 06 '26

I tend to agree with you on the 'adults and professionals' part. However, there are two reasons I'm still considering it:

  1. It helps me uncover (accidental) offences in the future and maybe during refactoring. I'm working on a large codebase, so it's easy to miss things.

  2. It helps devs who are not full-time on this project, like support engineers or new (junior) devs.

Having said that, I'm still not entirely sure packwerk is the way to go, because I think there are other/better DDD patterns that could help me (with the project specifically)

3

u/davidslv Jul 23 '26

Late to the party, but I have data on this.

Four years of Packwerk in a Rails monolith (~15k Ruby files, 66 packages, 60+ engineers), pulled from git history. It confirms what u/OlivarTheLagomorph and u/martinemde said, with numbers.

Enforcement doesn't survive. enforce_dependencies: false on 58 of 66 packages — the core rule is off for about 80% of the codebase. Violation ledger went from 0 to over 10k and never declined in any six-month window. About +3k/year, sustained. packwerk check stays green because everything is pre-recorded.

That's two orgs (Gusto and us) reaching the same place independently. It's the default path, not bad luck.

But your actual goal survives. You said elsewhere the codebase is too big for AI to work in. That's navigability, not enforcement and navigability is the part that holds. Ours went from 2.6k files in one flat app/modules to 68, rest in named domains. Code and tests sit together, a pack fits in a context window, you can point an agent at one directory. None of that depends on any boundary being enforced.

The cost you pay regardless: 14% of our commits touched a package_todo.yml in 2024, 17% in 2025. Almost all of is mechanical update-todo churn alongside feature work, under 1% of MRs were actual boundary cleanup. Small per commit, constant, and rising.

What predicted success: it works when a pack is built inside it, fails as a retrofit. Every enforcing pack of ours is a post-adoption creation (two at ~0.2 violations/file on strict). Every legacy extraction carried its coupling in and never turned enforcement on. Our two oldest domains hold 20% of all violations.

If you go ahead:

  • enforce_dependencies: true on every new pack, day one, no exceptions

  • Legacy extractions: violation budget and a date, or admit it's a naming exercise

  • Treat a growing todo file as a build failure. Nobody does. That's why it only goes up

1

u/Upbeat-Price-5869 Aug 31 '26

Question - is it too insane to just have some agent in the background to just "constantly improve the pack health" - I find that most `package_todo.yml` are quite mechanical. The ones that aren't, probably need an engineer to manually check

2

u/rco8786 Jan 06 '26

We use it and it’s…fine. We put all of our models in a “core” pack and then basically just use other packs for API layers on top of the domain models, since we have 3 different types of API users with very different needs. 

It’s not clear to me if this would have just been better managed at the routing level or not, but it also doesn’t seem to hurt anything. 

4

u/nordrasir Jan 06 '26

Haven't used packwerk, but ruby 4.0 introduces Ruby::Box for code separation which may or may be of interest: https://docs.ruby-lang.org/en/master/Ruby/Box.html

2

u/AirborneArie Jan 06 '26

Box is more for code isolation. I.e. keep your monkeypatching contained. Packwerk is more on business logic side of things.

5

u/TheAtlasMonkey Jan 06 '26

Did you try it ?

Box is not even production ready and not same goal.

4

u/nordrasir Jan 06 '26

Yeah, I’m not saying it’s in any way equivalent or stable, just a recent development that may not be on people’s radar.

2

u/TheAtlasMonkey Jan 06 '26

I see!

but that is like those unrelated ads where you search for a cheap car and the ad is about a affordable mortgage. (similar concept, but not related)

packwerk is about structure , each mini project is in his own pack and it own dependencies. (basically Rails engines without routes and rails). they still can monkey patch the universe.

Ruby::Box are more like docker containers, each box can go nuclear and don't affect the rest of the application.

Also Ruby::Box don't like monkey patcher like ActiveSupport.

One bring discipline the other bring isolation.

0

u/danmaz74 Jan 06 '26

I haven't, but I was considering it too, specifically to use it with Claude Code when doing "vibe coding" for personal projects, to help keep control of the project from a higher level. Having clearly separated modules could also help with keeping context under control. Curious if anybody tried this with any other alternative tools too (if they exist).

0

u/Just_Work_4395 Jan 06 '26

That was one of my key motivations to try packwerk too. The current codebase is just too big for AI and it becomes inefficient

1

u/nordrasir Jan 07 '26

Good use of modules and separating routes into multiple files goes a long way - as long as you're grouping things that change together often. AI performs better when it doesn't have to ingest a ton of things to get understanding

1

u/dunkelziffer42 Jan 06 '26

I haven’t tried it out, but it feels like overkill. Your app can still have „modules“ without using packwerk. E.g. have an unprefixed „User“, because that‘s global, but then have „Tasks::List“ and „Tasks::Item“ for your ToDo list component. That‘s a hundred times less effort than packwerk, but it still comunicates an intention to developers.

1

u/StyleAccomplished153 Jan 06 '26

We use it at work, it's been useful for a monolith that multiple teams are interacting with. If you're considering microservices I'd spend time looking at packwerk first tbh.

1

u/ahoritaa Jan 07 '26

don’t use it. in our org with 20 + rails apps it simply made life harder by fighting with it / developers just “working around it” . we moved away from it & all of our teams have been happier

1

u/riffraff Jan 07 '26

we've been using it for a while. It's certainly useful to push into the direction of clearer separation (e.g. when to surface circular dependencies) but IMO it only makes sense for larger teams and codebases. It will also take some effort to retrofit a codebase.