ombulabs/claude-code_rails-upgrade-skill / rails-upgrade
rails-upgrade
VerifiedAnalyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.
references/js-compressor-sprockets-mismatch-reference.md
View on GitHub# JS Compressor vs Sprockets During a Dual-Boot Upgrade
**When to read this:** the `JS_COMPRESSOR_GEM_MISMATCH` detection pattern fired, i.e. the
Gemfile has `gem "terser"` and you are dual-booting across a Rails
version that locks Sprockets to the 2.x line (Rails 4.0 via `sprockets-rails`).
If the app uses plain `uglifier`, you do not need this file. The standard
`config.assets.js_compressor = :uglifier` fix is enough.
---
## The problem in one paragraph
terser's `Terser::Compressor` (`lib/terser/compressor.rb`) does `require "sprockets/digest_utils"`, and
its railtie references that class at boot. `sprockets/digest_utils` exists only in **Sprockets >= 3**. Rails 4.0 pins Sprockets to **2.x**.
The next bundle *resolves* fine (so `railsbump` / `next_rails` report nothing), but at **boot**
Bundler auto-requires the gem, the railtie runs, and you get:
```
LoadError: cannot load such file -- sprockets/digest_utils
```
The failure is require-time, not resolve-time, which is why dependency checkers miss it.
## Why not just use uglifier on the next side?
Because apps add terser on purpose. Uglifier's last release (4.2.0, Sep 2019) is abandoned and
cannot compile modern JS:
- ES2020 optional chaining `?.` and nullish coalescing `??` — not parsed at all, even with
`harmony: true`.
- UTF-8 source files — uglifier defaults to US-ASCII and errors on smart quotes, em-dashes, etc.
Swapping terser for uglifier on the next side would drop exactly the assets that motivated
terser. The goal is to keep terser working on **both** sides.
---
## The recipe
### Gemfile
```ruby
group :assets do
if next?
gem "uglifier", ">= 1.3.0" # ONLY so the :uglifier symbol resolves in env configs
gem "terser", require: false # the real compressor; require: false is MANDATORY (see below)
else
gem "terser" # current side: railtie is harmless on Sprockets 2.x there
end
end
```
**Why `require: false` on the next side is mandatory.** Without it, Bundler auto-requires
terser at boot, the railtie runs `config.assets.configure { ... }`, that block references
`Terser::Compressor`, which autoloads and `require "sprockets/digest_utils"` — and boot dies.
With `require: false`, the railtie never runs; you load terser yourself at compile time.
**Why uglifier is still present on the next side.** Env configs set
`config.assets.js_compressor = :uglifier` (see below). Sprockets 2.x resolves `:uglifier` to its
built-in `UglifierCompressor`. The gem must be installed for the symbol to resolve, even though
its JS engine never actually runs in production — the rake task replaces it with Terser first.
### Environment configs (production / staging / etc.)
```ruby
config.assets.js_compressor = :uglifier
```
Unconditional is fine: `:uglifier` resolves on both Sprockets 2.x (next) and the current side.
### Rake task: swap in Terser at compile time
Hook on `assets:environment` (runs before compilation) and replace the registered `:uglifier`
processor with Terser:
```ruby
# lib/tasks/assets.rake
Rake::Task["assets:environment"].enhance do
require "terser"
env = Rails.application.assets
env = env.instance_variable_get(:@environment) if env.is_a?(Sprockets::Index)
terser = Terser.new(output: { ecma: 2015 })
env.js_compressor = nil # unregisters the :uglifier bundle processor set in env configs
env.register_bundle_processor("application/javascript", :js_compressor) do |context, data|
if context.pathname.to_s.include?("/webpack/") || context.pathname.basename.to_s.include?(".min.")
data # already minified — skip
else
terser.compile(data)
end
end
Rails.application.assets = env.index if Rails.application.assets.is_a?(Sprockets::Index)
end
```
On a current Rails 3.2 side the equivalent uses `Sprockets::LazyCompressor` (defined in
ActionPack 3.2, not the Sprockets gem) wrapping a `Terser.new`, gated on `config.assets.compress`
so it only runs in production-like environments.
---
## Cleanup on the next hop (when Sprockets reaches 3/4)
Once the app is fully on a Rails version that ships Sprockets 3/4, unwind the workaround:
1. Drop `uglifier` — it was only a symbol shim.
2. Drop `require: false` on terser — Sprockets 3/4 integrates `Terser::Compressor` natively via
the railtie.
3. Delete the rake-task swap — terser registers itself.
4. Remove the `:uglifier` assignment / any `NextRails.next?` guards in env configs.
---
## Notes
- Use `NextRails.next?` for any runtime branching, never `respond_to?` or `Gem::Version`
comparisons.
- The exact hop where this bites is wherever Sprockets is still pinned to 2.x — for the
3.2 → 4.0 upgrade that is the 4.0 side. An app that already has Sprockets 3/4 will not hit it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |