Skip to content

ombulabs/claude-code_rails-upgrade-skill / rails-upgrade

rails-upgrade

Verified

Analyzes 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.

FileKindSize
SKILL.mdskill md11.0 KB
detection-scripts/gem_limits.rbscript6.0 KB
detection-scripts/hop.rbscript2.2 KB
detection-scripts/patterns/rails-40-patterns.expectations.ymlconfig43.8 KB
detection-scripts/patterns/rails-40-patterns.ymlconfig96.5 KB
detection-scripts/patterns/rails-41-patterns.expectations.ymlconfig25.6 KB
detection-scripts/patterns/rails-41-patterns.ymlconfig59.8 KB
detection-scripts/patterns/rails-42-patterns.expectations.ymlconfig27.5 KB
detection-scripts/patterns/rails-42-patterns.ymlconfig48.7 KB
detection-scripts/patterns/rails-50-patterns.expectations.ymlconfig1.9 KB
detection-scripts/patterns/rails-50-patterns.ymlconfig8.1 KB
detection-scripts/patterns/rails-51-patterns.expectations.ymlconfig4.2 KB
detection-scripts/patterns/rails-51-patterns.ymlconfig15.0 KB
detection-scripts/patterns/rails-52-patterns.expectations.ymlconfig5.0 KB
detection-scripts/patterns/rails-52-patterns.ymlconfig14.7 KB
detection-scripts/patterns/rails-60-patterns.expectations.ymlconfig1007 B
detection-scripts/patterns/rails-60-patterns.ymlconfig14.2 KB
detection-scripts/patterns/rails-70-patterns.expectations.ymlconfig4.0 KB
detection-scripts/patterns/rails-70-patterns.ymlconfig11.2 KB
detection-scripts/patterns/rails-71-patterns.expectations.ymlconfig3.1 KB
detection-scripts/patterns/rails-71-patterns.ymlconfig9.5 KB
detection-scripts/patterns/rails-72-patterns.expectations.ymlconfig1.2 KB
detection-scripts/patterns/rails-72-patterns.ymlconfig6.1 KB
detection-scripts/patterns/rails-80-patterns.expectations.ymlconfig6.6 KB
detection-scripts/patterns/rails-80-patterns.ymlconfig21.2 KB
detection-scripts/patterns/rails-81-patterns.expectations.ymlconfig4.3 KB
detection-scripts/patterns/rails-81-patterns.ymlconfig13.2 KB
detection-scripts/scan_patterns.rbscript42.8 KB
examples/multi-hop-upgrade.mdmarkdown18.9 KB
examples/simple-upgrade.mdmarkdown4.0 KB
references/breaking-changes-by-version-reference.mdmarkdown3.9 KB
references/deprecation-warnings-reference.mdmarkdown10.7 KB
references/gem-compatibility-reference.mdmarkdown8.2 KB
references/js-compressor-sprockets-mismatch-reference.mdmarkdown4.7 KB
references/multi-hop-strategy-reference.mdmarkdown8.8 KB
references/next-hop-readiness-reference.mdmarkdown2.1 KB
references/no-test-suite-smoke-reference.mdmarkdown4.7 KB
references/request-patterns-reference.mdmarkdown3.7 KB
references/sequential-strategy-reference.mdmarkdown2.1 KB
references/staying-current-reference.mdmarkdown7.8 KB
references/testing-checklist-reference.mdmarkdown6.3 KB
templates/app-update-preview-template.mdmarkdown4.3 KB
templates/upgrade-report-template.mdmarkdown10.2 KB
version-guides/upgrade-3.2-to-4.0.mdmarkdown68.0 KB
version-guides/upgrade-4.0-to-4.1.mdmarkdown66.7 KB
version-guides/upgrade-4.1-to-4.2.mdmarkdown60.7 KB
version-guides/upgrade-4.2-to-5.0.mdmarkdown9.7 KB
version-guides/upgrade-5.0-to-5.1.mdmarkdown19.1 KB
version-guides/upgrade-5.1-to-5.2.mdmarkdown17.7 KB
version-guides/upgrade-5.2-to-6.0.mdmarkdown6.4 KB
version-guides/upgrade-6.0-to-6.1.mdmarkdown6.8 KB
version-guides/upgrade-6.1-to-7.0.mdmarkdown14.7 KB
version-guides/upgrade-7.0-to-7.1.mdmarkdown13.2 KB
version-guides/upgrade-7.1-to-7.2.mdmarkdown11.2 KB
version-guides/upgrade-7.2-to-8.0.mdmarkdown23.1 KB
version-guides/upgrade-8.0-to-8.1.mdmarkdown14.0 KB
workflows/00-verify-latest-patch-workflow.mdmarkdown1.7 KB
workflows/01-run-test-suite-workflow.mdmarkdown12.7 KB
workflows/02-resolve-deprecation-warnings-workflow.mdmarkdown6.3 KB
workflows/03-validate-upgrade-path-workflow.mdmarkdown1.8 KB
workflows/04-setup-next-rails-workflow.mdmarkdown1.5 KB
workflows/05-detect-breaking-changes-workflow.mdmarkdown20.0 KB
workflows/06-check-gem-compatibility-workflow.mdmarkdown11.1 KB
workflows/07-boot-smoke-test-workflow.mdmarkdown7.3 KB
workflows/08-generate-upgrade-report-workflow.mdmarkdown12.7 KB
workflows/09-generate-app-update-preview-workflow.mdmarkdown7.3 KB
workflows/10-implement-and-upgrade-workflow.mdmarkdown2.5 KB
workflows/11-sync-ci-workflow.mdmarkdown8.6 KB
workflows/12-align-load-defaults-workflow.mdmarkdown952 B
workflows/13-mention-cleanup-workflow.mdmarkdown1.3 KB

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.
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall