You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

Walkthrough

This PR makes documentation-only edits across many docs: command examples now favor Bundler/rake, Node and dependency guidance updated, API/config examples switched to symbol-keyed access, bundler/transpiler/React/TypeScript docs revised, and several small formatting and example fixes.

Changes

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

• Rake tasks should be called with rake, instead of rails #830: Similar documentation changes replacing direct CLI/ruby task invocations with Bundler/rake equivalents (matches command-invocation edits in this PR).

Poem

🐰 Hop, hop — the docs refreshed and bright,
Commands now routed by rake's soft light,
Node twenty marching, types and React in tow,
Bundlers sorted, examples all aglow,
I nibble crumbs of changelog joy and go!

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Greptile Summary

This is a docs-only sweep across 22 files that fixes stale commands, broken local links, and outdated version/API guidance accumulated since the Shakapacker v9 release. No source code is changed.\n\nKey corrections made:\n- bin/shakapacker clobber/compile replaced with bundle exec rake shakapacker:clobber/compile throughout (docs/common-upgrades.md, docs/transpiler-migration.md, docs/using_swc_loader.md)\n- Node.js minimum bumped from 14 to 20 in README badge and requirements table\n- docs/react.md simplified from a Babel-only, step-by-step guide to an SWC-first setup with proper HMR instructions for both webpack and rspack\n- docs/rspack_migration_guide.md rake flag syntax corrected with -- separator so CLI args are passed to the task rather than interpreted by rake\n- docs/api-reference.md scrubbed of non-existent methods and updated return-type examples\n- docs/transpiler-migration.md SWC config examples wrapped in the required options: key\n- Husky v9 setup commands in CONTRIBUTING.md updated from deprecated husky install/husky add to npx husky\n- Heroku push command updated from git push heroku master to git push heroku HEAD:main\n- Dead link in docs/typescript-migration.md replaced with a valid absolute GitHub URL

Confidence Score: 5/5

Safe to merge — docs-only change set with no source code modifications and no test-suite impact.

All 22 changed files are documentation. The corrections are accurate and well-scoped. The two P2 comments are non-blocking style suggestions and do not affect correctness of the rest of the PR.

docs/api-reference.md (return-type examples worth a spot-check against source), docs/transpiler-migration.md (active assets_bundler: webpack key in transpiler-selection YAML block)

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User installs Shakapacker] --> B{Choose bundler}
    B -->|webpack| C[config/webpack/webpack.config.js]
    B -->|rspack| D[config/rspack/rspack.config.js]
    C --> E{Choose transpiler}
    D --> E
    E -->|swc default| F[SWC via swc-loader]
    E -->|babel| G[Babel via babel-loader]
    E -->|esbuild| H[esbuild via esbuild-loader]
    F --> I{HMR enabled?}
    G --> I
    H --> I
    I -->|webpack + HMR| J[react-refresh-webpack-plugin auto-added]
    I -->|rspack + HMR| K[rspack plugin-react-refresh auto-added]
    I -->|no HMR| L[Production build via bundle exec rake]
    J --> M[bin/shakapacker-dev-server]
    K --> M

_{Reviews (1): Last reviewed commit: "docs: fix stale and broken guides" | Re-trigger Greptile}

test comment

Documentation Review

Overall this is a solid docs pass — most corrections are accurate against the actual source code. Two issues worth addressing before merge, plus one pre-existing bug worth fixing since the surrounding code is being touched.

Overall this PR is a solid docs cleanup. One factual error is flagged inline on docs/api-reference.md line 460. Positive callouts: swc.config.js options wrapper fix aligns with using_swc_loader.md; symbol key corrections for config.data are accurate; removing non-existent API methods (status_url, asset_url, last_compilation_digest, CompilationError etc) is good cleanup; manifest.refresh return value is correctly documented; CDN manifest clarification is accurate; NODE_ENV behaviour fix in v9_upgrade.md matches the actual source code; rake task -- separator matches the task documented usage.

Review: Fix stale and broken documentation

Overall this is a well-scoped docs clean-up. Most of the factual corrections are verified against the source code and accurate:

• symbol-keyed config.data — confirmed by lib/shakapacker/configuration.rb (@return [Hash<Symbol, Object>])
• public_output_path returns a Pathname — confirmed (public_path.join(...))
• assets_bundler_config_path returns a String — confirmed
• additional_paths returns raw strings — confirmed (fetch(:additional_paths))
• Removed CompilationError / InvalidConfigurationError — neither class exists in the codebase; removal is correct
• Removed dev_server.asset_url / dev_server.status_url — neither method exists; removal is correct
• dev_server.protocol / dev_server.host_with_port — both exist in lib/shakapacker/dev_server.rb
• SWC config options: wrapper — correct per package/swc/index.ts (merge(defaultConfig, customConfig) expects the custom config at the RuleSetRule level, so options.jsc maps cleanly)
• CSS modules exportLocalsConvention: "camelCase" — matches the actual v8-compat path in package/utils/getStyleRule.ts (line 49–52)
• NODE_ENV unset → "production" — confirmed by lib/shakapacker.rb:112 (DEV_ENVS.include?(ENV["RAILS_ENV"]) ? "development" : "production"); nil is not in DEV_ENVS, so unset RAILS_ENV correctly maps to production
• bin/rake shakapacker:switch_bundler -- --init-config — the -- separator is required per the rake task's own usage string (lib/tasks/shakapacker/switch_bundler.rake:22)

Two concrete issues flagged inline:

1. docs/troubleshooting.md:259 — gem 'shakapacker', '~> 9.1' permits 9.1.0 (the unfixed version); the minimum should be ~> 9.1.1 to match the stated "v9.1.1+" requirement.
2. docs/cdn_setup.md:209 — the grep /packs/ check does not verify that asset tags include the CDN host; it passes even when CDN is not configured. Should grep for the CDN hostname instead.

Review posted with 2 inline comments. Summary: docs/troubleshooting.md:261 needs tilde constraint fixed (~> 9.1 -> ~> 9.1.1), and docs/cdn_setup.md:210 grep command needs to check CDN hostname not /packs/ path. NODE_ENV claim in v9_upgrade.md is correct (CodeRabbit was wrong).

Documentation Review

Verified all API examples against the current source code. The corrections are accurate and the overall quality is high.

Verified correct:

• config.data symbol keys — configuration.rb confirms @return [Hash<Symbol, Object>] and deep_symbolize_keys on load
• public_output_path return type — public_path.join(...) returns a Pathname, not a bare string
• additional_paths return type — fetch(:additional_paths) returns strings, not Pathnames
• assets_bundler_config_path return type — returns a plain string (e.g. "config/webpack")
• dev_server[:server] — dev_server.rb has def server (not https?); removed status_url / asset_url which do not exist
• compiler.fresh? / compiler.stale? — both are delegated via delegate :fresh?, :stale?, to: :strategy in compiler.rb
• manifest.refresh return value — correctly returns the manifest hash; manifest.data correctly removed (it is private)
• Removed CompilationError / InvalidConfigurationError — neither class exists in the codebase
• Removed last_compilation_digest, watched_paths, config_files — none exist on Compiler
• Fixed broken link — webpack-configuration.md does not exist; configuration.md does
• Node 20+ — confirmed by package.json engines field
• bundle exec rake test — correct; the Rakefile runs run_spec:all_specs (more comprehensive than bare rspec)
• bin/shakapacker clobber/compile replaced with rake shakapacker:clobber/compile — correct, Runner has no such subcommands
• Peer dependency ranges in docs/peer-dependencies.md — all match package.json
• Husky v9 commands — npx husky is correct for ^9.1.7

One behavioral change to be aware of:

docs/css-modules-export-mode.md Option 2 changes exportLocalsConvention from "asIs" to "camelCase". With namedExport: false, "asIs" exports only the literal class name (styles["my-button"]), while "camelCase" also adds a camelCase alias (styles.myButton). This change makes Option 2 consistent with what Option 1 (css_modules_export_mode: default) does internally — Shakapacker sets camelCase in its built-in default mode, not asIs. So the original example was the inconsistency. Left an inline note since it is a real behavioral difference for anyone relying on the old example to avoid camelCase aliasing.

Minor nit:

docs/api-reference.md removes the manifest.data example without any note. Since manifest.data is private this is the right call, but a brief comment pointing to manifest.refresh might help readers who expected a read-only accessor.