shakapacker 9.2.0 → 9.3.0.beta.0

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

@@ -10,8 +10,8 @@ In pure JavaScript projects, you can use true named imports:
 
 ```js
 // v9 - named exports in JavaScript
-import { bright, container } from './Foo.module.css';
-<button className={bright} />
+import { bright, container } from "./Foo.module.css"
+;<button className={bright} />
 ```
 
 ### TypeScript Usage
@@ -27,6 +27,7 @@ import * as styles from './Foo.module.css';
 **Why namespace imports?** While webpack's css-loader generates true named exports at runtime (with `namedExport: true`), TypeScript's type system cannot determine these dynamic exports during compilation. The namespace import pattern allows TypeScript to treat the import as an object with string keys, bypassing the need for static export validation while still benefiting from the runtime optimizations of named exports.
 
 ### Benefits of v9 Configuration
+
 - Eliminates certain webpack warnings
 - Provides better tree-shaking potential
 - Aligns with modern JavaScript module standards
@@ -37,6 +38,7 @@ import * as styles from './Foo.module.css';
 When `namedExport: true` is enabled (v9 default), css-loader requires `exportLocalsConvention` to be either `'camelCaseOnly'` or `'dashesOnly'`.
 
 **The following will cause a build error:**
+
 ```js
 modules: {
   namedExport: true,
@@ -45,11 +47,13 @@ modules: {
 ```
 
 **Error message:**
+
 ```
 "exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option
 ```
 
 **Correct v9 configuration:**
+
 ```js
 modules: {
   namedExport: true,
@@ -60,23 +64,26 @@ modules: {
 **exportLocalsConvention options with namedExport:**
 
 When `namedExport: true`, you can use:
+
 - `'camelCaseOnly'` (v9 default): Exports ONLY the camelCase version (e.g., only `myButton`)
 - `'dashesOnly'`: Exports ONLY the original kebab-case version (e.g., only `my-button`)
 
 **Not compatible with namedExport: true:**
+
 - `'camelCase'`: Exports both versions (both `my-button` and `myButton`) - only works with `namedExport: false` (v8 behavior)
 
 **Configuration Quick Reference:**
 
-| namedExport | exportLocalsConvention | `.my-button` exports | Use Case | Compatible? |
-|-------------|------------------------|---------------------|----------|-------------|
-| `true` | `'camelCaseOnly'` | `myButton` | JavaScript conventions | ✅ Valid |
-| `true` | `'dashesOnly'` | `'my-button'` | Preserve CSS naming | ✅ Valid |
-| `false` | `'camelCase'` | Both `myButton` AND `'my-button'` | v8 compatibility | ✅ Valid |
-| `false` | `'asIs'` | `'my-button'` | No transformation | ✅ Valid |
-| `true` | `'camelCase'` | - | - | ❌ Build Error |
+| namedExport | exportLocalsConvention | `.my-button` exports              | Use Case               | Compatible?    |
+| ----------- | ---------------------- | --------------------------------- | ---------------------- | -------------- |
+| `true`      | `'camelCaseOnly'`      | `myButton`                        | JavaScript conventions | ✅ Valid       |
+| `true`      | `'dashesOnly'`         | `'my-button'`                     | Preserve CSS naming    | ✅ Valid       |
+| `false`     | `'camelCase'`          | Both `myButton` AND `'my-button'` | v8 compatibility       | ✅ Valid       |
+| `false`     | `'asIs'`               | `'my-button'`                     | No transformation      | ✅ Valid       |
+| `true`      | `'camelCase'`          | -                                 | -                      | ❌ Build Error |
 
 **When to use each option:**
+
 - Use `'camelCaseOnly'` if you prefer standard JavaScript naming conventions
 - Use `'dashesOnly'` if you want to preserve your CSS class names exactly as written
 - Use `'camelCase'` (with `namedExport: false`) only if you need both versions available
@@ -87,8 +94,8 @@ In Shakapacker v8 and earlier, the default behavior was to use a **default expor
 
 ```js
 // v8 and earlier default
-import styles from './Foo.module.css';
-<button className={styles.bright} />
+import styles from "./Foo.module.css"
+;<button className={styles.bright} />
 ```
 
 ---
@@ -102,21 +109,23 @@ When upgrading to Shakapacker v9, you'll need to update your CSS Module imports
 #### Option 1: Update Your Code (Recommended)
 
 **For JavaScript projects:**
+
 ```js
 // Before (v8)
-import styles from './Component.module.css';
-<div className={styles.container}>
+import styles from "./Component.module.css"
+;<div className={styles.container}>
   <button className={styles.button}>Click me</button>
 </div>
 
 // After (v9) - JavaScript
-import { container, button } from './Component.module.css';
-<div className={container}>
+import { container, button } from "./Component.module.css"
+;<div className={container}>
   <button className={button}>Click me</button>
 </div>
 ```
 
 **For TypeScript projects:**
+
 ```typescript
 // Before (v8)
 import styles from './Component.module.css';
@@ -149,44 +158,44 @@ This approach modifies the common webpack configuration that applies to all envi
 
 ```js
 // config/webpack/commonWebpackConfig.js
-const { generateWebpackConfig, merge } = require('shakapacker');
+const { generateWebpackConfig, merge } = require("shakapacker")
 
-const baseClientWebpackConfig = generateWebpackConfig();
+const baseClientWebpackConfig = generateWebpackConfig()
 
 // Override CSS Modules configuration to use v8-style default exports
 const overrideCssModulesConfig = (config) => {
   // Find the CSS rule in the module rules
-  const cssRule = config.module.rules.find(rule =>
-    rule.test && rule.test.toString().includes('css')
-  );
+  const cssRule = config.module.rules.find(
+    (rule) => rule.test && rule.test.toString().includes("css")
+  )
 
   if (cssRule && cssRule.use) {
-    const cssLoaderUse = cssRule.use.find(use =>
-      use.loader && use.loader.includes('css-loader')
-    );
+    const cssLoaderUse = cssRule.use.find(
+      (use) => use.loader && use.loader.includes("css-loader")
+    )
 
     if (cssLoaderUse && cssLoaderUse.options && cssLoaderUse.options.modules) {
       // Override v9 default to use v8-style default exports
-      cssLoaderUse.options.modules.namedExport = false;
-      cssLoaderUse.options.modules.exportLocalsConvention = 'asIs';
+      cssLoaderUse.options.modules.namedExport = false
+      cssLoaderUse.options.modules.exportLocalsConvention = "asIs"
     }
   }
 
-  return config;
-};
+  return config
+}
 
 const commonOptions = {
   resolve: {
-    extensions: ['.css', '.ts', '.tsx'],
-  },
-};
+    extensions: [".css", ".ts", ".tsx"]
+  }
+}
 
 const commonWebpackConfig = () => {
-  const config = merge({}, baseClientWebpackConfig, commonOptions);
-  return overrideCssModulesConfig(config);
-};
+  const config = merge({}, baseClientWebpackConfig, commonOptions)
+  return overrideCssModulesConfig(config)
+}
 
-module.exports = commonWebpackConfig;
+module.exports = commonWebpackConfig
 ```
 
 ### Option 2: Create `config/webpack/environment.js` (Alternative)
@@ -195,8 +204,8 @@ If you prefer using a separate environment file:
 
 ```js
 // config/webpack/environment.js
-const { environment } = require('@shakacode/shakapacker');
-const getStyleRule = require('@shakacode/shakapacker/package/utils/getStyleRule');
+const { environment } = require("@shakacode/shakapacker")
+const getStyleRule = require("@shakacode/shakapacker/package/utils/getStyleRule")
 
 // CSS Modules rule for *.module.css with v8-style default export
 const cssModulesRule = getStyleRule(/\.module\.css$/i, [], {
@@ -204,14 +213,14 @@ const cssModulesRule = getStyleRule(/\.module\.css$/i, [], {
   importLoaders: 2,
   modules: {
     auto: true,
-    namedExport: false,            // <-- override v9 default
-    exportLocalsConvention: 'asIs' // keep class names as-is instead of camelCase
+    namedExport: false, // <-- override v9 default
+    exportLocalsConvention: "asIs" // keep class names as-is instead of camelCase
   }
-});
+})
 
 // Ensure this rule wins for *.module.css
 if (cssModulesRule) {
-  environment.loaders.prepend('css-modules', cssModulesRule);
+  environment.loaders.prepend("css-modules", cssModulesRule)
 }
 
 // Plain CSS rule for non-modules
@@ -219,13 +228,13 @@ const plainCssRule = getStyleRule(/(?<!\.module)\.css$/i, [], {
   sourceMap: true,
   importLoaders: 2,
   modules: false
-});
+})
 
 if (plainCssRule) {
-  environment.loaders.append('css', plainCssRule);
+  environment.loaders.append("css", plainCssRule)
 }
 
-module.exports = environment;
+module.exports = environment
 ```
 
 Then reference this in your environment-specific configs (development.js, production.js, etc.).
@@ -238,25 +247,32 @@ If you also use Sass modules, add similar configuration for SCSS files:
 // For Option 1 approach, extend the overrideCssModulesConfig function:
 const overrideCssModulesConfig = (config) => {
   // Handle both CSS and SCSS rules
-  const styleRules = config.module.rules.filter(rule =>
-    rule.test && (rule.test.toString().includes('css') || rule.test.toString().includes('scss'))
-  );
-
-  styleRules.forEach(rule => {
+  const styleRules = config.module.rules.filter(
+    (rule) =>
+      rule.test &&
+      (rule.test.toString().includes("css") ||
+        rule.test.toString().includes("scss"))
+  )
+
+  styleRules.forEach((rule) => {
     if (rule.use) {
-      const cssLoaderUse = rule.use.find(use =>
-        use.loader && use.loader.includes('css-loader')
-      );
-
-      if (cssLoaderUse && cssLoaderUse.options && cssLoaderUse.options.modules) {
-        cssLoaderUse.options.modules.namedExport = false;
-        cssLoaderUse.options.modules.exportLocalsConvention = 'asIs';
+      const cssLoaderUse = rule.use.find(
+        (use) => use.loader && use.loader.includes("css-loader")
+      )
+
+      if (
+        cssLoaderUse &&
+        cssLoaderUse.options &&
+        cssLoaderUse.options.modules
+      ) {
+        cssLoaderUse.options.modules.namedExport = false
+        cssLoaderUse.options.modules.exportLocalsConvention = "asIs"
       }
     }
-  });
+  })
 
-  return config;
-};
+  return config
+}
 ```
 
 ---
@@ -269,10 +285,10 @@ const overrideCssModulesConfig = (config) => {
 
 ```js
 // Old (v8 - default export)
-import styles from './Component.module.css';
+import styles from "./Component.module.css"
 
 // New (v9 - named exports)
-import { bright, container, button } from './Component.module.css';
+import { bright, container, button } from "./Component.module.css"
 ```
 
 #### 2. Update Class References
@@ -305,8 +321,8 @@ With `exportLocalsConvention: 'camelCaseOnly'`, kebab-case class names are autom
 
 ```js
 // v9 default - camelCase conversion
-import { myButton, primaryColor } from './styles.module.css';
-<button className={myButton} />
+import { myButton, primaryColor } from "./styles.module.css"
+;<button className={myButton} />
 ```
 
 **Option B: Keep kebab-case with 'dashesOnly'**
@@ -339,30 +355,33 @@ For large codebases, you can create a codemod to automate the migration:
 
 ```js
 // css-modules-v9-migration.js
-module.exports = function(fileInfo, api) {
-  const j = api.jscodeshift;
-  const root = j(fileInfo.source);
-  
+module.exports = function (fileInfo, api) {
+  const j = api.jscodeshift
+  const root = j(fileInfo.source)
+
   // Find CSS module imports
-  root.find(j.ImportDeclaration, {
-    source: { value: value => value.endsWith('.module.css') }
-  }).forEach(path => {
-    const defaultSpecifier = path.node.specifiers.find(
-      spec => spec.type === 'ImportDefaultSpecifier'
-    );
-    
-    if (defaultSpecifier) {
-      // Convert default import to namespace import for analysis
-      // Then extract used properties and convert to named imports
-      // ... codemod implementation
-    }
-  });
-  
-  return root.toSource();
-};
+  root
+    .find(j.ImportDeclaration, {
+      source: { value: (value) => value.endsWith(".module.css") }
+    })
+    .forEach((path) => {
+      const defaultSpecifier = path.node.specifiers.find(
+        (spec) => spec.type === "ImportDefaultSpecifier"
+      )
+
+      if (defaultSpecifier) {
+        // Convert default import to namespace import for analysis
+        // Then extract used properties and convert to named imports
+        // ... codemod implementation
+      }
+    })
+
+  return root.toSource()
+}
 ```
 
 Run with:
+
 ```bash
 npx jscodeshift -t css-modules-v9-migration.js src/
 ```
@@ -371,14 +390,14 @@ npx jscodeshift -t css-modules-v9-migration.js src/
 
 ## Version Comparison
 
-| Feature | v8 (and earlier) | v9 |
-|---------|-----------------|----|
-| Default behavior | Default export object | Named exports |
-| Import syntax | `import styles from '...'` | `import { className } from '...'` |
-| Class reference | `styles.className` | `className` |
-| Export convention | `asIs` (no transformation) | `camelCaseOnly` |
-| TypeScript warnings | May show warnings | No warnings |
-| Tree-shaking | Limited | Optimized |
+| Feature             | v8 (and earlier)           | v9                                |
+| ------------------- | -------------------------- | --------------------------------- |
+| Default behavior    | Default export object      | Named exports                     |
+| Import syntax       | `import styles from '...'` | `import { className } from '...'` |
+| Class reference     | `styles.className`         | `className`                       |
+| Export convention   | `asIs` (no transformation) | `camelCaseOnly`                   |
+| TypeScript warnings | May show warnings          | No warnings                       |
+| Tree-shaking        | Limited                    | Optimized                         |
 
 ---
 
@@ -419,12 +438,12 @@ Verify your imports work correctly:
 
 ```js
 // v9 default (named exports)
-import { bright } from './Foo.module.css';
-console.log(bright); // 'Foo_bright__hash'
+import { bright } from "./Foo.module.css"
+console.log(bright) // 'Foo_bright__hash'
 
 // Or if using v8 configuration (default export)
-import styles from './Foo.module.css';
-console.log(styles); // { bright: 'Foo_bright__hash' }
+import styles from "./Foo.module.css"
+console.log(styles) // { bright: 'Foo_bright__hash' }
 ```
 
 ### 3. Debug Webpack Configuration (Optional)
@@ -444,6 +463,7 @@ Then search for `css-loader` options in the generated JSON file.
 ### Build Error: exportLocalsConvention Incompatible with namedExport
 
 If you see this error during build:
+
 ```
 "exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option
 ```
@@ -477,9 +497,9 @@ If your CSS classes aren't applying after the upgrade:
 
 ```typescript
 // src/types/css-modules.d.ts
-declare module '*.module.css' {
-  const classes: { [key: string]: string };
-  export = classes;
+declare module "*.module.css" {
+  const classes: { [key: string]: string }
+  export = classes
 }
 ```
 
@@ -487,9 +507,9 @@ declare module '*.module.css' {
 
 ```typescript
 // src/types/css-modules.d.ts
-declare module '*.module.css' {
-  const classes: { [key: string]: string };
-  export default classes;
+declare module "*.module.css" {
+  const classes: { [key: string]: string }
+  export default classes
 }
 ```
 

data/docs/customizing_babel_config.md

@@ -1,14 +1,13 @@
 # Customizing Babel Config
 
 ## Default Configuration
+
 The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
 
 ```json
 {
   "babel": {
-    "presets": [
-      "./node_modules/shakapacker/package/babel/preset.js"
-    ]
+    "presets": ["./node_modules/shakapacker/package/babel/preset.js"]
   }
 }
 ```
@@ -22,7 +21,7 @@ This is a very basic skeleton that you can use that includes the Shakapacker pre
 ```js
 // babel.config.js
 module.exports = function (api) {
-  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const defaultConfigFunc = require("shakapacker/package/babel/preset.js")
   const resultConfig = defaultConfigFunc(api)
 
   const changesOnDefault = {
@@ -31,7 +30,7 @@ module.exports = function (api) {
     ].filter(Boolean),
     plugins: [
       // put custom plugins here
-    ].filter(Boolean),
+    ].filter(Boolean)
   }
 
   resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
@@ -55,30 +54,31 @@ And then update the configuration:
 ```js
 // babel.config.js
 module.exports = function (api) {
-  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const defaultConfigFunc = require("shakapacker/package/babel/preset.js")
   const resultConfig = defaultConfigFunc(api)
-  const isDevelopmentEnv = api.env('development')
-  const isProductionEnv = api.env('production')
-  const isTestEnv = api.env('test')
+  const isDevelopmentEnv = api.env("development")
+  const isProductionEnv = api.env("production")
+  const isTestEnv = api.env("test")
 
   const changesOnDefault = {
     presets: [
       [
-        '@babel/preset-react',
+        "@babel/preset-react",
         {
           development: isDevelopmentEnv || isTestEnv,
           useBuiltIns: true
-        } 
+        }
       ]
     ].filter(Boolean),
     plugins: [
-      isProductionEnv && ['babel-plugin-transform-react-remove-prop-types', 
-        { 
-          removeImport: true 
+      isProductionEnv && [
+        "babel-plugin-transform-react-remove-prop-types",
+        {
+          removeImport: true
         }
       ],
-      process.env.WEBPACK_SERVE && 'react-refresh/babel'
-    ].filter(Boolean),
+      process.env.WEBPACK_SERVE && "react-refresh/babel"
+    ].filter(Boolean)
   }
 
   resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]

data/docs/deployment.md

@@ -3,6 +3,24 @@
 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`.
 
+**📖 For configuration options, see the [Configuration Guide](./configuration.md)**
+
+## Precompile Hook
+
+Shakapacker supports running a custom command before webpack compilation via the `precompile_hook` configuration option. This is useful for dynamically generating entry points (e.g., for React on Rails) or performing other preparatory tasks.
+
+**Note:** The precompile hook runs in both development and production environments. For complete documentation, see the [Precompile Hook Guide](precompile_hook.md).
+
+Quick example for production deployment:
+
+```yaml
+# config/shakapacker.yml
+production:
+  precompile_hook: "bin/rails react_on_rails:generate_packs"
+```
+
+This ensures your dynamic entry points are generated before `assets:precompile` runs.
+
 ## Heroku
 
 In order for your Shakapacker app to run on Heroku, you'll need to do a bit of configuration before hand.

data/docs/developing_shakapacker.md

@@ -3,19 +3,25 @@
 It's a little trickier for Rails developers to work on the JS code of a project like shakacode/shakapacker. So here are some tips!
 
 ## Use some test app
+
 For example, for React on Rails Changes, I'm using [shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh](https://github.com/shakacode/react_on_rails_tutorial_with_ssr_and_hmr_fast_refresh).
 This directory is the `TEST_APP_DIR`.
 
 ## Fork shakacode/shakapacker
+
 Let's call the shakacode/shakapacker directory `SHAKAPACKER_DIR` which has shakacode/shakapacker's `package.json`.
 
 ## Changing the Package
+
 ### Setup with Yalc
+
 Use [`yalc`](https://github.com/wclr/yalc) unless you like yak shaving weird errors.
+
 1. In `SHAKAPACKER_DIR`, run `yalc publish`
 2. In `TEST_APP_DIR`, run `yalc link shakapacker`
 
 ## Update the Package Code
+
 1. Make some JS change in SHAKAPACKER_DIR
 2. Run `yalc push` and your changes will be pushed to your `TEST_APP_DIR`'s node_modules.
 3. You may need to run `yarn` in `TEST_APP_DIR` if you added or removed dependencies of shakacode/shakapacker.

data/docs/optional-peer-dependencies.md

@@ -20,16 +20,16 @@ As of Shakapacker v9, all peer dependencies are marked as optional via `peerDepe
   "dependencies": {
     "js-yaml": "^4.1.0",
     "path-complete-extname": "^1.0.0",
-    "webpack-merge": "^5.8.0"  // Direct dependency - always available
+    "webpack-merge": "^5.8.0" // Direct dependency - always available
   },
   "peerDependencies": {
     "webpack": "^5.76.0",
-    "@rspack/core": "^1.0.0",
+    "@rspack/core": "^1.0.0"
     // ... all build tools
   },
   "peerDependenciesMeta": {
     "webpack": { "optional": true },
-    "@rspack/core": { "optional": true },
+    "@rspack/core": { "optional": true }
     // ... all marked as optional
   }
 }
@@ -49,6 +49,7 @@ Type-only imports are erased during compilation and don't trigger module resolut
 ## Configuration Examples
 
 ### Webpack + Babel (Traditional)
+
 ```json
 {
   "dependencies": {
@@ -63,6 +64,7 @@ Type-only imports are erased during compilation and don't trigger module resolut
 ```
 
 ### Webpack + SWC (20x Faster)
+
 ```json
 {
   "dependencies": {
@@ -76,6 +78,7 @@ Type-only imports are erased during compilation and don't trigger module resolut
 ```
 
 ### Rspack + SWC (10x Faster Bundling)
+
 ```json
 {
   "dependencies": {
@@ -100,6 +103,7 @@ If upgrading from Shakapacker v8:
 ### New Installations
 
 The installer (`rails shakapacker:install`) only adds packages needed for your configuration:
+
 - Detects your preferred bundler (webpack/rspack)
 - Installs appropriate JavaScript transpiler (babel/swc/esbuild)
 - Adds only required dependencies
@@ -129,12 +133,13 @@ Verify Shakapacker loads without optional dependencies:
 
 ```javascript
 // This works even without webpack installed (when using rspack)
-const shakapacker = require('shakapacker');
+const shakapacker = require("shakapacker")
 ```
 
 ### CI Integration
 
 The test suite includes:
+
 - `spec/shakapacker/optional_dependencies_spec.rb` - Package.json structure validation
 - `spec/shakapacker/doctor_optional_peer_spec.rb` - Doctor command validation
 - `test/peer-dependencies.sh` - Installation warning tests