shakapacker 9.1.0 → 9.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f96f94846c3ee598308246c0098532ba6248fded2b0d3b3aba786e03f7fcfb9
-  data.tar.gz: 85d79f4ff3ad8a6e6383e5e30a0f834fa8400ea31588b839ca6dae13b8f77f9f
+  metadata.gz: 5ac40ff5ddf8db373b1de0efaf805a033d7ba87641d84bde529669761b8e64d2
+  data.tar.gz: 5d0abb49ede8ad2aa37c94e9148e4def579c3eabb8c6e8d94a127796941ed559
 SHA512:
-  metadata.gz: 102139fc016e4eb974e0f9b8888355f64723cc78281c13c7c4688e4f3f8c563f8436fd042838593c7356108212b48b7d298cbd9c4b6a86331a92557120750577
-  data.tar.gz: 7cde64aa9e306826463966f1092c365dc7bc8e1d7447c04995408b25d21e1ddac27af2fa998d075afeb6d4c4f04bae83c88e99d89eec150455c862135ed74168
+  metadata.gz: 5309f5d9beef93aaa0434e0e8ab93118545ecad507ade518ab56a332980d804536e36762670d21245d67d6c60e126367b1ea4edd8e4766daf20c294871ea1263
+  data.tar.gz: 4fb22afab6e203194018a1be9096aac472bffdbc08d58fc7a5b04a23c5e5d8c52084a17830d8ffb5156a6e4798de061f6f671474638616b7ffecd6c6348916f5

data/.gitignore

@@ -16,6 +16,9 @@ gemfiles/*.lock
 .yalc
 yalc.lock
 
+# Config exporter output directory
+shakapacker-config-exports/
+
 # TypeScript generated files
 package/**/*.d.ts
 package/**/*.d.ts.map

data/CHANGELOG.md

@@ -11,7 +11,38 @@
 
 Changes since the last non-beta release.
 
-_No unreleased changes._
+## [v9.1.1] - October 9, 2025
+
+### Added
+
+- **New config export utility for debugging webpack/rspack configurations** [PR #647](https://github.com/shakacode/shakapacker/pull/647) by [justin808](https://github.com/justin808).
+  - Adds `bin/export-bundler-config` utility with three modes:
+    - **Doctor mode** (`--doctor`): Exports all configs (dev + prod, client + server) to `shakapacker-config-exports/` directory - best for troubleshooting
+    - **Save mode** (`--save`): Export current environment configs to files
+    - **Stdout mode** (default): View configs in terminal
+  - **Output formats:** YAML (with optional inline documentation), JSON, or Node.js inspect
+  - **Smart features:**
+    - Environment isolation ensures dev/prod configs are truly different
+    - Auto-detects bundler from `shakapacker.yml`
+    - Pretty-prints functions (up to 50 lines)
+    - Validates bundler value and output paths
+    - Sanitizes filenames to prevent path traversal
+    - Helpful `.gitignore` suggestions
+  - **Usage:** `bin/export-bundler-config --doctor` or `bundle exec rake shakapacker:export_bundler_config`
+  - Works seamlessly with `rake shakapacker:switch_bundler` for comparing webpack vs rspack configs
+  - Lays groundwork for future config diff feature (tracked in [#667](https://github.com/shakacode/shakapacker/issues/667))
+
+### Fixed
+
+- Fixed NoMethodError when custom environment (e.g., staging) is not defined in shakapacker.yml. [PR #669](https://github.com/shakacode/shakapacker/pull/669) by [justin808](https://github.com/justin808).
+  - When deploying to environments like Heroku staging with `RAILS_ENV=staging`, shakapacker would crash with `undefined method 'deep_symbolize_keys' for nil:NilClass`
+  - **Configuration fallback:** Now properly falls back to production environment configuration (appropriate for staging)
+  - **NODE_ENV handling:** `bin/shakapacker` now automatically sets `NODE_ENV=production` for custom environments (staging, etc.)
+    - Previously: `RAILS_ENV=staging` would set `NODE_ENV=development`, breaking webpack optimizations
+    - Now: `RAILS_ENV` in `[development, test]` uses that value for `NODE_ENV`, everything else uses `production`
+  - Logs informational message when falling back to help with debugging
+  - This ensures shakapacker works with any Rails environment even if not explicitly defined in shakapacker.yml
+  - Fixes [#663](https://github.com/shakacode/shakapacker/issues/663)
 
 ## [v9.1.0] - October 8, 2025
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.1.0)
+    shakapacker (9.2.0)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/README.md

@@ -767,6 +767,27 @@ Please note that if you want opt-in to use esbuild-loader, you can skip [React](
 
 To switch between Babel, SWC, or esbuild, or to configure environment-specific transpiler settings, see the [Transpiler Migration Guide](./docs/transpiler-migration.md).
 
+### Debugging Configuration
+
+Shakapacker provides a powerful utility to export and analyze your webpack/rspack configuration:
+
+```bash
+# Export all configs for troubleshooting (recommended)
+bin/export-bundler-config --doctor
+
+# Or via rake task
+bundle exec rake shakapacker:export_bundler_config -- --doctor
+```
+
+This exports development and production configurations for both client and server bundles to `shakapacker-config-exports/` directory in annotated YAML format. Perfect for:
+
+- Debugging configuration issues
+- Comparing webpack vs rspack configs (works with `rake shakapacker:switch_bundler`)
+- Understanding differences between development and production
+- Analyzing client vs server bundle configurations
+
+For more options and usage examples, see the [Troubleshooting Guide](./docs/troubleshooting.md#exporting-webpack--rspack-configuration).
+
 ### Integrations
 
 Shakapacker out of the box supports JS and static assets (fonts, images etc.) compilation. To enable support for CoffeeScript or TypeScript install relevant packages:

data/bin/export-bundler-config

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// Minimal shim - all logic is in the TypeScript module
+const { run } = require('shakapacker/configExporter')
+
+run(process.argv.slice(2))
+  .then((exitCode) => process.exit(exitCode))
+  .catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })

data/docs/deployment.md

@@ -3,8 +3,6 @@
 Shakapacker hooks up a new `shakapacker:compile` task to `assets:precompile`, which gets run whenever you run `assets:precompile`.
 If you are not using Sprockets `shakapacker:compile` is automatically aliased to `assets:precompile`.
 
-```
-
 ## Heroku
 
 In order for your Shakapacker app to run on Heroku, you'll need to do a bit of configuration before hand.
@@ -19,13 +17,59 @@ git push heroku master
 
 We're essentially doing the following here:
 
-* Creating an app on Heroku
-* Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
-* Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
-* Pushing your code to Heroku and kicking off the deployment
+- Creating an app on Heroku
+- Creating a Postgres database for the app (this is assuming that you're using Heroku Postgres for your app)
+- Adding the Heroku NodeJS and Ruby buildpacks for your app. This allows the `npm` or `yarn` executables to properly function when compiling your app - as well as Ruby.
+- Pushing your code to Heroku and kicking off the deployment
 
 Your production build process is responsible for installing your JavaScript dependencies before `rake assets:precompile`. For example, if you are on Heroku, the `heroku/nodejs` buildpack must run **prior** to the `heroku/ruby` buildpack for precompilation to run successfully.
 
+### Custom Rails Environments (e.g., staging)
+
+**Key distinction:**
+
+- **RAILS_ENV** is used to look up configuration in `config/shakapacker.yml`
+- **NODE_ENV** is used by your `webpack.config.js` (or `rspack.config.js`) for build optimizations
+
+**Good news:** As of this version, `bin/shakapacker` automatically sets `NODE_ENV=production` for custom environments like staging:
+
+```bash
+# NODE_ENV automatically set to 'production' for staging
+RAILS_ENV=staging bin/shakapacker
+
+# Also works with rake task
+RAILS_ENV=staging bundle exec rails assets:precompile
+```
+
+**How it works:**
+
+- `RAILS_ENV=development` → `NODE_ENV=development`
+- `RAILS_ENV=test` → `NODE_ENV=test`
+- `RAILS_ENV=production` → `NODE_ENV=production`
+- Any other custom env → `NODE_ENV=production`
+
+**Configuration fallback:**
+
+You don't need to add custom environments to your `shakapacker.yml`. Shakapacker automatically falls back to production-like defaults:
+
+1. First, it looks for the environment you're deploying to (e.g., `staging`)
+2. If not found, it falls back to `production` configuration
+
+This means staging environments automatically use production settings (compile: false, cache_manifest: true, etc.).
+
+**Optional: Staging-specific configuration**
+
+If you want different settings for staging, explicitly add a `staging` section:
+
+```yaml
+staging:
+  <<: *default
+  compile: false
+  cache_manifest: true
+  # Staging-specific overrides (e.g., different output path)
+  public_output_path: packs-staging
+```
+
 ## Nginx
 
 Shakapacker doesn't serve anything in production. You’re expected to configure your web server to serve files in public/ directly.
@@ -117,10 +161,10 @@ namespace :deploy do
   desc "Run rake js install"
   task :js_install do
     require "package_json"
-    
+
     # this will use the package manager specified via `packageManager`, or otherwise fallback to `npm`
     native_js_install_command = PackageJson.read.manager.native_install_command(frozen: true).join(" ")
-    
+
     on roles(:web) do
       within release_path do
         execute("cd #{release_path} && #{native_js_install_command}")

data/docs/releasing.md

@@ -0,0 +1,197 @@
+# Releasing Shakapacker
+
+This guide is for Shakapacker maintainers who need to publish a new release.
+
+## Prerequisites
+
+1. **Install required tools:**
+
+   ```bash
+   bundle install              # Installs gem-release
+   yarn global add release-it  # Installs release-it for npm publishing
+   ```
+
+2. **Ensure you have publishing access:**
+
+   - npm: You must be a collaborator on the [shakapacker npm package](https://www.npmjs.com/package/shakapacker)
+   - RubyGems: You must be an owner of the [shakapacker gem](https://rubygems.org/gems/shakapacker)
+
+3. **Enable 2FA on both platforms:**
+   - npm: 2FA is required for publishing
+   - RubyGems: 2FA is required for publishing
+
+## Release Process
+
+### 1. Prepare the Release
+
+Before running the release task:
+
+1. Ensure all desired changes are merged to `main` branch
+2. Update `CHANGELOG.md` with the new version and release notes
+3. Commit the CHANGELOG changes
+4. Ensure your working directory is clean (`git status` shows no uncommitted changes)
+
+### 2. Run the Release Task
+
+The automated release task handles the entire release process:
+
+```bash
+# For a specific version (e.g., 9.1.0)
+rake create_release[9.1.0]
+
+# For a beta release (note: use period, not dash)
+rake create_release[9.2.0.beta.1]  # Creates npm package 9.2.0-beta.1
+
+# For a patch version bump (auto-increments)
+rake create_release
+
+# Dry run to test without publishing
+rake create_release[9.1.0,true]
+```
+
+### 3. What the Release Task Does
+
+The `create_release` task automatically:
+
+1. **Pulls latest changes** from the repository
+2. **Bumps version numbers** in:
+   - `lib/shakapacker/version.rb` (Ruby gem version)
+   - `package.json` (npm package version - converted from Ruby format)
+3. **Publishes to npm:**
+   - Prompts for npm OTP (2FA code)
+   - Creates git tag
+   - Pushes to GitHub
+4. **Publishes to RubyGems:**
+   - Prompts for RubyGems OTP (2FA code)
+5. **Updates spec/dummy lockfiles:**
+   - Runs `bundle install` to update `Gemfile.lock`
+   - Runs `npm install` to update `package-lock.json` (yarn.lock may also be updated for multi-package-manager compatibility testing)
+6. **Commits and pushes lockfile changes** automatically
+
+### 4. Version Format
+
+**Important:** Use Ruby gem version format (no dashes):
+
+- ✅ Correct: `9.1.0`, `9.2.0.beta.1`, `9.0.0.rc.2`
+- ❌ Wrong: `9.1.0-beta.1`, `9.0.0-rc.2`
+
+The task automatically converts Ruby gem format to npm semver format:
+
+- Ruby: `9.2.0.beta.1` → npm: `9.2.0-beta.1`
+- Ruby: `9.0.0.rc.2` → npm: `9.0.0-rc.2`
+
+**Examples:**
+
+```bash
+# Regular release
+rake create_release[9.1.0]  # Gem: 9.1.0, npm: 9.1.0
+
+# Beta release
+rake create_release[9.2.0.beta.1]  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
+
+# Release candidate
+rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+```
+
+### 5. During the Release
+
+1. When prompted for **npm OTP**, enter your 2FA code from your authenticator app
+2. Accept defaults for release-it options
+3. When prompted for **RubyGems OTP**, enter your 2FA code
+4. The script will automatically commit and push lockfile updates
+
+### 6. After Release
+
+1. Verify the release on:
+
+   - [npm](https://www.npmjs.com/package/shakapacker)
+   - [RubyGems](https://rubygems.org/gems/shakapacker)
+   - [GitHub releases](https://github.com/shakacode/shakapacker/releases)
+
+2. Check that the lockfile commit was pushed:
+
+   ```bash
+   git log --oneline -5
+   # Should see "Update spec/dummy lockfiles after release"
+   ```
+
+3. Announce the release (if appropriate):
+   - Post in relevant Slack/Discord channels
+   - Tweet about major releases
+   - Update documentation if needed
+
+## Troubleshooting
+
+### Uncommitted Changes After Release
+
+If you see uncommitted changes to lockfiles after a release, this means:
+
+1. The release was successful but the lockfile commit step may have failed
+2. **Solution:** Manually commit these files:
+   ```bash
+   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
+   git commit -m 'Update spec/dummy lockfiles after release'
+   git push
+   ```
+
+### Failed npm or RubyGems Publish
+
+If publishing fails partway through:
+
+1. Check which step failed (npm or RubyGems)
+2. If npm failed: Fix the issue and manually run `npm publish`
+3. If RubyGems failed: Fix the issue and manually run `gem release`
+4. Then manually update and commit spec/dummy lockfiles
+
+### Wrong Version Format
+
+If you accidentally use npm format (with dashes):
+
+1. The gem will be created with an invalid version
+2. **Solution:** Don't push the changes, reset your branch:
+   ```bash
+   git reset --hard HEAD
+   ```
+3. Re-run with correct Ruby gem format
+
+## Manual Release Steps
+
+If you need to release manually (not recommended):
+
+1. **Bump version:**
+
+   ```bash
+   gem bump --version 9.1.0
+   bundle install
+   ```
+
+2. **Publish to npm:**
+
+   ```bash
+   release-it 9.1.0 --npm.publish
+   ```
+
+3. **Publish to RubyGems:**
+
+   ```bash
+   gem release
+   ```
+
+4. **Update lockfiles:**
+   ```bash
+   cd spec/dummy
+   bundle install
+   npm install
+   cd ../..
+   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
+   git commit -m 'Update spec/dummy lockfiles after release'
+   git push
+   ```
+
+## Questions?
+
+If you encounter issues not covered here, please:
+
+1. Check the [CONTRIBUTING.md](../CONTRIBUTING.md) guide
+2. Ask in the maintainers channel
+3. Update this documentation for future releases

data/docs/rspack_migration_guide.md

@@ -269,6 +269,34 @@ bin/shakapacker --mode production
 3. **Enable Caching:** Rspack has built-in persistent caching
 4. **Use SWC:** The built-in SWC loader is significantly faster than Babel
 
+## Debugging Configuration
+
+To compare your webpack and rspack configurations during migration:
+
+```bash
+# Export webpack configs before switching
+bin/export-bundler-config --doctor
+
+# Switch to rspack
+rails shakapacker:switch_bundler rspack --install-deps
+
+# Export rspack configs to compare
+bin/export-bundler-config --doctor
+
+# Compare the files in shakapacker-config-exports/
+diff shakapacker-config-exports/webpack-production-client.yaml \
+     shakapacker-config-exports/rspack-production-client.yaml
+```
+
+The config export utility creates annotated YAML files that make it easy to:
+
+- Verify plugin replacements are correct
+- Compare loader configurations
+- Identify missing or different options
+- Debug configuration issues
+
+See the [Troubleshooting Guide](./troubleshooting.md#exporting-webpack--rspack-configuration) for more details.
+
 ## Resources
 
 - [Rspack Documentation](https://rspack.rs)