shakapacker 9.3.0 → 9.3.2

data/docs/css-modules-export-mode.md

@@ -150,11 +150,45 @@ If you prefer to keep the v8 default export behavior during migration, you can o
 
 ## Reverting to Default Exports (v8 Behavior)
 
-To use the v8-style default exports instead of v9's named exports:
+To use the v8-style default exports instead of v9's named exports, you have several options:
 
-### Option 1: Update `config/webpack/commonWebpackConfig.js` (Recommended)
+### Option 1: Configuration File (Easiest - Recommended)
 
-This approach modifies the common webpack configuration that applies to all environments:
+The simplest way to restore v8 behavior is to set the `css_modules_export_mode` option in your `config/shakapacker.yml`:
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  # ... other settings ...
+
+  # CSS Modules export mode
+  # named (default) - Use named exports with camelCase conversion (v9 default)
+  # default - Use default export with both original and camelCase names (v8 behavior)
+  css_modules_export_mode: default
+```
+
+This configuration automatically adjusts the CSS loader settings:
+
+- Sets `namedExport: false` to enable default exports
+- Sets `exportLocalsConvention: 'camelCase'` to export both original and camelCase versions
+
+**Restart your development server** after changing this setting for the changes to take effect.
+
+With this configuration, you can continue using v8-style imports:
+
+```js
+// Works with css_modules_export_mode: default
+import styles from "./Component.module.css"
+;<div className={styles.container}>
+  <button className={styles.button}>Click me</button>
+  <button className={styles["my-button"]}>Kebab-case</button>
+  <button className={styles.myButton}>Also available</button>
+</div>
+```
+
+### Option 2: Manual Webpack Configuration (Advanced)
+
+If you need more control or can't use the configuration file approach, you can manually modify the webpack configuration that applies to all environments:
 
 ```js
 // config/webpack/commonWebpackConfig.js
@@ -198,7 +232,7 @@ const commonWebpackConfig = () => {
 module.exports = commonWebpackConfig
 ```
 
-### Option 2: Create `config/webpack/environment.js` (Alternative)
+### Option 3: Create `config/webpack/environment.js` (Alternative)
 
 If you prefer using a separate environment file:
 
@@ -239,12 +273,12 @@ module.exports = environment
 
 Then reference this in your environment-specific configs (development.js, production.js, etc.).
 
-### Option 3: (Optional) Sass Modules
+### Option 4: (Optional) Sass Modules
 
 If you also use Sass modules, add similar configuration for SCSS files:
 
 ```js
-// For Option 1 approach, extend the overrideCssModulesConfig function:
+// For Option 2 approach (manual webpack config), extend the overrideCssModulesConfig function:
 const overrideCssModulesConfig = (config) => {
   // Handle both CSS and SCSS rules
   const styleRules = config.module.rules.filter(

data/docs/deployment.md

@@ -16,7 +16,7 @@ Quick example for production deployment:
 ```yaml
 # config/shakapacker.yml
 production:
-  precompile_hook: "bin/rails react_on_rails:generate_packs"
+  precompile_hook: "bin/rake react_on_rails:generate_packs"
 ```
 
 This ensures your dynamic entry points are generated before `assets:precompile` runs.
@@ -56,7 +56,7 @@ Your production build process is responsible for installing your JavaScript depe
 RAILS_ENV=staging bin/shakapacker
 
 # Also works with rake task
-RAILS_ENV=staging bundle exec rails assets:precompile
+RAILS_ENV=staging bundle exec rake assets:precompile
 ```
 
 **How it works:**
@@ -156,7 +156,7 @@ Shakapacker supports serving JavaScript bundles and assets from a CDN. For a com
 
 ```bash
 export SHAKAPACKER_ASSET_HOST=https://cdn.example.com
-RAILS_ENV=production bundle exec rails assets:precompile
+RAILS_ENV=production bundle exec rake assets:precompile
 ```
 
 Note: Shakapacker does NOT use the `ASSET_HOST` environment variable. You must use `SHAKAPACKER_ASSET_HOST` instead (`WEBPACKER_ASSET_HOST` if using Shakapacker before v7).

data/docs/early_hints_manual_api.md

@@ -399,7 +399,7 @@ development: # or production
 bundle exec puma --early-hints
 
 # Option 2: Test in production mode locally (more realistic)
-RAILS_ENV=production rails assets:precompile  # Compile assets first
+RAILS_ENV=production bundle exec rake assets:precompile  # Compile assets first
 RAILS_ENV=production bundle exec puma --early-hints -e production
 ```
 

data/docs/feature_testing.md

@@ -434,7 +434,7 @@ curl http://localhost:3035/packs/application.js
 
 Use this checklist to verify a complete Shakapacker setup:
 
-- [ ] **Assets compile:** `bundle exec rails assets:precompile` succeeds
+- [ ] **Assets compile:** `bundle exec rake assets:precompile` succeeds
 - [ ] **Manifest exists:** `public/packs/manifest.json` contains entrypoints
 - [ ] **Assets load:** Page loads without 404s for pack files
 - [ ] **Code splitting works:** Multiple chunks load in Network tab
@@ -456,7 +456,7 @@ cat public/packs/manifest.json | jq .
 **Recompile:**
 
 ```bash
-bundle exec rails assets:precompile
+bundle exec rake assets:precompile
 ```
 
 ### Old Assets Cached
@@ -465,7 +465,7 @@ bundle exec rails assets:precompile
 
 ```bash
 rm -rf public/packs
-bundle exec rails assets:precompile
+bundle exec rake assets:precompile
 ```
 
 ### Dev Server Won't Start

data/docs/optional-peer-dependencies.md

@@ -102,7 +102,7 @@ If upgrading from Shakapacker v8:
 
 ### New Installations
 
-The installer (`rails shakapacker:install`) only adds packages needed for your configuration:
+The installer (`bundle exec rake shakapacker:install`) only adds packages needed for your configuration:
 
 - Detects your preferred bundler (webpack/rspack)
 - Installs appropriate JavaScript transpiler (babel/swc/esbuild)
@@ -159,7 +159,7 @@ The test suite includes:
 
 1. Check you've installed required dependencies for your configuration
 2. Refer to the configuration examples above
-3. Run `rails shakapacker:doctor` for diagnostics
+3. Run `bundle exec rake shakapacker:doctor` for diagnostics
 
 ### TypeScript errors?
 

data/docs/precompile_hook.md

@@ -14,14 +14,14 @@ This is useful for:
 
 The precompile hook is especially useful when you need to run commands like:
 
-- `bin/rails react_on_rails:generate_packs` - Generate dynamic entry points
-- `bin/rails react_on_rails:locale` - Generate locale files
+- `bin/rake react_on_rails:generate_packs` - Generate dynamic entry points
+- `bin/rake react_on_rails:locale` - Generate locale files
 - Any custom script that prepares files before asset compilation
 
 **Important:** The hook runs in **both development and production**:
 
 - **Development**: Runs before `bin/shakapacker --watch` or dev server starts
-- **Production**: Runs before `rails assets:precompile`
+- **Production**: Runs before `bundle exec rake assets:precompile`
 
 ## Configuration
 
@@ -39,7 +39,7 @@ development:
 
 production:
   <<: *default
-  precompile_hook: "bin/rails react_on_rails:generate_packs"
+  precompile_hook: "rake react_on_rails:generate_packs"
 ```
 
 ## Creating a Precompile Hook Script
@@ -51,8 +51,8 @@ production:
 # bin/shakapacker-precompile-hook
 
 echo "Preparing assets..."
-bin/rails react_on_rails:generate_packs
-bin/rails react_on_rails:locale
+bundle exec rake react_on_rails:generate_packs
+bundle exec rake react_on_rails:locale
 echo "Assets prepared successfully"
 ```
 
@@ -117,14 +117,14 @@ For React on Rails projects, the hook replaces manual steps in your workflow:
 
 ```bash
 # Development
-bin/rails react_on_rails:generate_packs
-bin/rails react_on_rails:locale
+bundle exec rake react_on_rails:generate_packs
+bundle exec rake react_on_rails:locale
 bin/shakapacker-dev-server
 
 # Production
-bin/rails react_on_rails:generate_packs
-bin/rails react_on_rails:locale
-RAILS_ENV=production bin/rails assets:precompile
+bundle exec rake react_on_rails:generate_packs
+bundle exec rake react_on_rails:locale
+RAILS_ENV=production rake assets:precompile
 ```
 
 ### After (Automatic)
@@ -138,8 +138,8 @@ default: &default
 ```bash
 #!/usr/bin/env bash
 # bin/react-on-rails-hook
-bin/rails react_on_rails:generate_packs
-bin/rails react_on_rails:locale
+bundle exec rake react_on_rails:generate_packs
+bundle exec rake react_on_rails:locale
 ```
 
 Now simply run:
@@ -149,7 +149,7 @@ Now simply run:
 bin/shakapacker-dev-server
 
 # Production
-RAILS_ENV=production bin/rails assets:precompile
+RAILS_ENV=production bin/rake assets:precompile
 ```
 
 ## Security
@@ -292,7 +292,7 @@ default:
 
 if [ "$RAILS_ENV" = "production" ]; then
   echo "Running production-specific setup..."
-  bin/rails react_on_rails:generate_packs
+  bin/rake react_on_rails:generate_packs
 else
   echo "Running development setup..."
   # Lighter-weight setup for development

data/docs/react.md

@@ -132,7 +132,7 @@ rails new myapp --skip-javascript
 cd myapp
 bundle add shakapacker --strict
 ./bin/bundle install
-./bin/rails shakapacker:install
+bundle exec rake shakapacker:install
 npm install react react-dom @babel/preset-react
 npm install css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
 ```

data/docs/releasing.md

@@ -36,16 +36,16 @@ 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]
+bundle exec 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
+bundle exec 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
+bundle exec rake create_release
 
 # Dry run to test without publishing
-rake create_release[9.1.0,true]
+bundle exec rake create_release[9.1.0,true]
 ```
 
 ### 3. What the Release Task Does
@@ -83,13 +83,13 @@ The task automatically converts Ruby gem format to npm semver format:
 
 ```bash
 # Regular release
-rake create_release[9.1.0]  # Gem: 9.1.0, npm: 9.1.0
+bundle exec 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
+bundle exec 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
+bundle exec rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
 ```
 
 ### 5. During the Release

data/docs/rspack_migration_guide.md

@@ -212,28 +212,22 @@ Shakapacker provides a convenient rake task to switch between webpack and rspack
 
 ```bash
 # Switch to rspack with automatic dependency management
-rails shakapacker:switch_bundler rspack --install-deps
-# or with rake (note the -- separator)
-rake shakapacker:switch_bundler rspack -- --install-deps
+bin/rake shakapacker:switch_bundler rspack -- --install-deps
 
 # Fast switching without uninstalling old bundler (keeps both)
-rails shakapacker:switch_bundler webpack --install-deps --no-uninstall
-rake shakapacker:switch_bundler rspack -- --install-deps --no-uninstall
+bin/rake shakapacker:switch_bundler rspack -- --install-deps --no-uninstall
 
 # Switch to rspack manually (you manage dependencies yourself)
-rails shakapacker:switch_bundler rspack
-rake shakapacker:switch_bundler rspack
+bin/rake shakapacker:switch_bundler rspack
 
 # Switch back to webpack if needed
-rails shakapacker:switch_bundler webpack --install-deps
-rake shakapacker:switch_bundler webpack -- --install-deps
+bin/rake shakapacker:switch_bundler webpack -- --install-deps
 
 # Show help
-rails shakapacker:switch_bundler --help
-rake shakapacker:switch_bundler -- --help
+bin/rake shakapacker:switch_bundler -- --help
 ```
 
-**Note:** When using `rake`, you must use `--` to separate rake options from task arguments.
+> **⚠️ Important:** This task must be run with `bin/rake`, not `bin/rails`.
 
 The task will:
 
@@ -246,7 +240,7 @@ The task will:
 **Custom Dependencies:** You can customize which dependencies are installed by creating a `.shakapacker-switch-bundler-dependencies.yml` file:
 
 ```bash
-rails shakapacker:switch_bundler --init-config
+bundle exec rake shakapacker:switch_bundler --init-config
 ```
 
 ### Manual Migration Steps
@@ -840,7 +834,7 @@ To compare your webpack and rspack configurations during migration:
 bin/shakapacker-config --doctor
 
 # Switch to rspack
-rails shakapacker:switch_bundler rspack --install-deps
+bundle exec rake shakapacker:switch_bundler rspack --install-deps
 
 # Export rspack configs to compare
 bin/shakapacker-config --doctor

data/docs/transpiler-migration.md

@@ -4,10 +4,13 @@
 
 ## Default Transpilers
 
-Shakapacker uses different default JavaScript transpilers based on the bundler:
+Shakapacker v9 transpiler defaults depend on the bundler and installation:
 
-- **Webpack**: `babel` (default) - Maintains backward compatibility
-- **Rspack**: `swc` (default) - Modern, faster transpiler for new bundler
+- **New installations (v9+)**: `swc` - Installation template explicitly sets SWC (20x faster than Babel)
+- **Webpack runtime default**: `babel` - Used when no explicit config is provided (maintains backward compatibility)
+- **Rspack runtime default**: `swc` - Rspack defaults to SWC as it's a newer bundler with modern defaults
+
+**Key distinction**: The installation template (`lib/install/config/shakapacker.yml`) explicitly sets `javascript_transpiler: "swc"` for new projects, but if you're upgrading or have no explicit config, webpack falls back to Babel for backward compatibility.
 
 ## Available Transpilers
 
@@ -22,15 +25,15 @@ Set the transpiler in your `config/shakapacker.yml`:
 
 ```yaml
 default: &default
-  # For webpack users (babel is default, no change needed)
-  javascript_transpiler: babel
-
-  # To opt-in to SWC for better performance
+  # SWC is the default (recommended - 20x faster than Babel)
   javascript_transpiler: swc
 
-  # For rspack users (swc is default, no change needed)
+  # To use Babel for backward compatibility
+  javascript_transpiler: babel
+
+  # For rspack users (defaults to swc if not specified)
   assets_bundler: rspack
-  javascript_transpiler: swc
+  # javascript_transpiler can be set, but rspack defaults to swc
 ```
 
 ## Migration Guide

data/docs/troubleshooting.md

@@ -280,7 +280,7 @@ See the [deployment guide](./deployment.md#custom-rails-environments-eg-staging)
 ## ENOENT: no such file or directory - node-sass
 
 If you get the error `ENOENT: no such file or directory - node-sass` on deploy with
-`assets:precompile` or `bundle exec rails shakapacker:compile` you may need to
+`assets:precompile` or `bundle exec rake shakapacker:compile` you may need to
 move Sass to production `dependencies`.
 
 Move any packages that related to Sass (e.g. `node-sass` or `sass-loader`) from
@@ -326,13 +326,13 @@ In `package.json`:
 
 ## webpack or webpack-dev-server not found
 
-- This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
+- This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rake shakapacker:install` to fix the issue.
 
 - If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
 
 ```bash
 bundle config --delete bin
-./bin/rails app:update:bin # or rails app:update:bin
+bundle exec rake app:update:bin
 ```
 
 ## Running webpack on Windows

data/docs/using_swc_loader.md

@@ -1,8 +1,6 @@
 # Using SWC Loader
 
-:warning: This feature is currently experimental. The configuration and API are subject to change during the beta release cycle.
-
-If you face any issues, please report at https://github.com/shakacode/shakapacker/issues.
+SWC is the recommended JavaScript transpiler in Shakapacker v9+, and is set as the default in new installations. If you face any issues, please report them at [Shakapacker Issues](https://github.com/shakacode/shakapacker/issues).
 
 ## About SWC
 
@@ -12,20 +10,23 @@ It supports all ECMAScript features and it's designed to be a drop-in replacemen
 
 For comparison between SWC and Babel, see the docs at https://swc.rs/docs/migrating-from-babel.
 
-> **Note:** SWC is also natively built into RSpack bundler, providing even faster compilation speeds. When using RSpack (`assets_bundler: 'rspack'`), SWC is used automatically regardless of the `javascript_transpiler` setting.
+> **Note:** SWC is also natively built into RSpack bundler, providing even faster compilation speeds. When using RSpack (`assets_bundler: 'rspack'`), SWC is the default if `javascript_transpiler` is not explicitly set.
+
+## Using SWC in your Shakapacker project
 
-## Switching your Shakapacker project to SWC
+For new installations of Shakapacker v9+, SWC is automatically configured in the installation template.
 
-In order to use SWC as your compiler today. You need to do two things:
+**Note**: While the installation template sets SWC as the default, webpack's runtime fallback (when no explicit config exists) remains Babel for backward compatibility. Rspack always defaults to SWC.
+
+If you're upgrading from v8 or earlier and want to switch from Babel to SWC:
 
 1. Make sure you've installed `@swc/core` and `swc-loader` packages.
 
-```
+```bash
 npm install @swc/core swc-loader
 ```
 
-2. Add or change `javascript_transpiler` value in your default `shakapacker.yml` config to `swc`
-   The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
+2. Confirm `javascript_transpiler` is set to `swc` in your `config/shakapacker.yml`:
 
 ```yml
 default: &default
@@ -43,7 +44,9 @@ default: &default
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false
 
-  # Select JavaScript transpiler to use, available options are 'babel' (default) or 'swc'
+  # Select JavaScript transpiler to use
+  # Available options: 'swc' (default, 20x faster), 'babel', or 'esbuild'
+  # Note: When using rspack, swc is used automatically regardless of this setting
   javascript_transpiler: "swc"
 ```
 

data/docs/v6_upgrade.md

@@ -80,7 +80,7 @@ _If you're on webpacker v5, follow [how to upgrade to webpacker v6.0.0.rc.6 from
    ```
 
    ```bash
-   bundle exec rails webpacker:install
+   bundle exec rake webpacker:install
    ```
 
    Overwrite all files and check what changed.
@@ -181,7 +181,7 @@ _If you're on webpacker v5, follow [how to upgrade to webpacker v6.0.0.rc.6 from
 
 1. Make sure that you can run `bin/webpack` without errors.
 
-1. Try running `RAILS_ENV=production bin/rails assets:precompile`. If all goes well, don't forget to clean the generated assets with `bin/rails assets:clobber`.
+1. Try running `RAILS_ENV=production rake assets:precompile`. If all goes well, don't forget to clean the generated assets with `rake assets:clobber`.
 
 1. Run `yarn add webpack-dev-server` if those are not already in your dev dependencies. Make sure you're using v4+.
 

data/docs/v9_upgrade.md

@@ -145,9 +145,84 @@ import * as styles from './Component.module.css';
    - TypeScript: Change to namespace imports (`import * as styles`)
    - Kebab-case class names are automatically converted to camelCase
 
-2. **Keep v8 behavior** temporarily:
-   - Override the css-loader configuration as shown in [CSS Modules Export Mode documentation](./css-modules-export-mode.md)
-   - This gives you time to migrate gradually
+2. **Keep v8 behavior** temporarily using configuration file (Easiest):
+
+   ```yaml
+   # config/shakapacker.yml
+   css_modules_export_mode: default
+   ```
+
+   This allows you to keep using default imports while migrating gradually
+
+3. **Keep v8 behavior** using webpack configuration (Advanced):
+
+   If you need more control over the configuration, you can override the css-loader settings directly in your webpack config.
+
+   **Where to add this:** Create or modify `config/webpack/webpack.config.js`. If this file doesn't exist, create it and ensure your `config/webpacker.yml` or build process loads it. See [Webpack Configuration](./webpack.md) for details on customizing webpack.
+
+   ```javascript
+   // config/webpack/webpack.config.js
+   const { generateWebpackConfig, merge } = require("shakapacker")
+
+   const customConfig = () => {
+     const config = merge({}, generateWebpackConfig())
+
+     // Override CSS Modules to use default exports (v8 behavior)
+     config.module.rules.forEach((rule) => {
+       if (
+         rule.test &&
+         (rule.test.test("example.module.scss") ||
+           rule.test.test("example.module.css"))
+       ) {
+         if (Array.isArray(rule.use)) {
+           rule.use.forEach((loader) => {
+             if (
+               loader.loader &&
+               loader.loader.includes("css-loader") &&
+               loader.options &&
+               loader.options.modules
+             ) {
+               // Disable named exports to support default imports
+               loader.options.modules.namedExport = false
+               loader.options.modules.exportLocalsConvention = "camelCase"
+             }
+           })
+         }
+       }
+     })
+
+     return config
+   }
+
+   module.exports = customConfig
+   ```
+
+   **Key points:**
+   - Test both `.module.scss` and `.module.css` file extensions
+   - Validate all loader properties exist before accessing them
+   - Use `.includes('css-loader')` since the loader path may vary
+   - Set both `namedExport: false` and `exportLocalsConvention: 'camelCase'` for full v8 compatibility
+
+   **Debugging tip:** To verify the override is applied correctly, you can inspect the webpack config:
+
+   ```javascript
+   // Add this temporarily to verify your changes
+   if (process.env.DEBUG_WEBPACK_CONFIG) {
+     const cssModuleRules = config.module.rules
+       .filter((r) => r.test?.test?.("example.module.css"))
+       .flatMap((r) => r.use?.filter((l) => l.loader?.includes("css-loader")))
+     console.log(
+       "CSS Module loader options:",
+       JSON.stringify(cssModuleRules, null, 2)
+     )
+   }
+   ```
+
+   Then run: `DEBUG_WEBPACK_CONFIG=true bin/shakapacker`
+
+   **Note:** This is a temporary solution. The recommended approach is to migrate your imports to use named exports as shown in the main documentation.
+
+   For detailed configuration options, see the [CSS Modules Export Mode documentation](./css-modules-export-mode.md)
 
 **Benefits of the change:**