shakapacker 9.0.0.beta.2 → 9.0.0.beta.3

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

@@ -1,26 +1,98 @@
 # CSS Modules Export Mode
 
-Most React guides and tutorials expect to import CSS Modules using a **default export object**:
+## Version 9.x (Current Default Behavior)
+
+Starting with Shakapacker v9, CSS Modules are configured with **named exports** (`namedExport: true`) by default to align with Next.js and modern tooling standards.
+
+### JavaScript Usage
+
+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} />
+```
+
+### TypeScript Usage
+
+TypeScript cannot statically analyze CSS files to determine the exact export names at compile time. When css-loader generates individual named exports dynamically from your CSS classes, TypeScript doesn't know what those exports will be. Therefore, you must use namespace imports:
+
+```typescript
+// v9 - namespace import required for TypeScript
+import * as styles from './Foo.module.css';
+<button className={styles.bright} />
+```
+
+**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
+- Automatically converts kebab-case to camelCase (`my-button` → `myButton`)
+
+## Version 8.x and Earlier Behavior
+
+In Shakapacker v8 and earlier, the default behavior was to use a **default export object**:
 
 ```js
+// v8 and earlier default
 import styles from './Foo.module.css';
 <button className={styles.bright} />
 ```
 
-However, depending on configuration, `css-loader` may instead emit **named exports**:
+---
+
+## Migrating from v8 to v9
+
+When upgrading to Shakapacker v9, you'll need to update your CSS Module imports from default exports to named exports.
+
+### Migration Options
 
+#### Option 1: Update Your Code (Recommended)
+
+**For JavaScript projects:**
 ```js
-import { bright } from './Foo.module.css';
-<button className={bright} />
+// Before (v8)
+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}>
+  <button className={button}>Click me</button>
+</div>
+```
+
+**For TypeScript projects:**
+```typescript
+// Before (v8)
+import styles from './Component.module.css';
+<div className={styles.container}>
+  <button className={styles.button}>Click me</button>
+</div>
+
+// After (v9) - TypeScript
+import * as styles from './Component.module.css';
+<div className={styles.container}>
+  <button className={styles.button}>Click me</button>
+</div>
 ```
 
-By default, Shakapacker currently leaves `css-loader`'s `modules.namedExport` option unset, which leads to **named exports** being used in many cases. This can surprise developers expecting the `import styles ...` pattern.
+Note: TypeScript projects only need to change from default import to namespace import (`* as styles`), the property access remains the same.
+
+#### Option 2: Keep v8 Behavior
+
+If you prefer to keep the v8 default export behavior during migration, you can override the configuration (see below).
 
 ---
 
-## How to Configure Shakapacker for Default Exports
+## Reverting to Default Exports (v8 Behavior)
 
-To force the more familiar `import styles ...` behavior (i.e. `namedExport: false`), update your webpack configuration as follows.
+To use the v8-style default exports instead of v9's named exports:
 
 ### Option 1: Update `config/webpack/commonWebpackConfig.js` (Recommended)
 
@@ -32,7 +104,7 @@ const { generateWebpackConfig, merge } = require('shakapacker');
 
 const baseClientWebpackConfig = generateWebpackConfig();
 
-// Override CSS Modules configuration to use default exports instead of named exports
+// 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 =>
@@ -45,7 +117,7 @@ const overrideCssModulesConfig = (config) => {
     );
 
     if (cssLoaderUse && cssLoaderUse.options && cssLoaderUse.options.modules) {
-      // Set namedExport to false for default export behavior
+      // Override v9 default to use v8-style default exports
       cssLoaderUse.options.modules.namedExport = false;
       cssLoaderUse.options.modules.exportLocalsConvention = 'asIs';
     }
@@ -77,14 +149,14 @@ If you prefer using a separate environment file:
 const { environment } = require('@shakacode/shakapacker');
 const getStyleRule = require('@shakacode/shakapacker/package/utils/getStyleRule');
 
-// CSS Modules rule for *.module.css with default export enabled
+// CSS Modules rule for *.module.css with v8-style default export
 const cssModulesRule = getStyleRule(/\.module\.css$/i, [], {
   sourceMap: true,
   importLoaders: 2,
   modules: {
     auto: true,
-    namedExport: false,            // <-- key: enable default export object
-    exportLocalsConvention: 'asIs' // keep your class names as-is
+    namedExport: false,            // <-- override v9 default
+    exportLocalsConvention: 'asIs' // keep class names as-is instead of camelCase
   }
 });
 
@@ -140,110 +212,157 @@ const overrideCssModulesConfig = (config) => {
 
 ---
 
-## Verifying the Configuration
+## Detailed Migration Guide
 
-### 1. Rebuild Your Packs
+### Migrating from v8 (Default Exports) to v9 (Named Exports)
 
-After making the configuration changes, rebuild your webpack bundles:
+#### 1. Update Import Statements
 
-```bash
-# For development
-NODE_ENV=development bin/shakapacker
+```js
+// Old (v8 - default export)
+import styles from './Component.module.css';
 
-# Or with the dev server
-bin/shakapacker-dev-server
+// New (v9 - named exports)
+import { bright, container, button } from './Component.module.css';
 ```
 
-### 2. Test in Your React Component
+#### 2. Update Class References
 
-Update your component to use default imports:
+```js
+// Old (v8)
+<div className={styles.container}>
+  <button className={styles.button}>Click me</button>
+  <span className={styles.bright}>Highlighted text</span>
+</div>
+
+// New (v9)
+<div className={container}>
+  <button className={button}>Click me</button>
+  <span className={bright}>Highlighted text</span>
+</div>
+```
+
+#### 3. Handle Kebab-Case Class Names
+
+With v9's `exportLocalsConvention: 'camelCase'`, kebab-case class names are automatically converted:
+
+```css
+/* styles.module.css */
+.my-button { ... }
+.primary-color { ... }
+```
 
 ```js
-// Before (named exports)
-import { bright } from './Foo.module.css';
+// v9 imports (camelCase conversion)
+import { myButton, primaryColor } from './styles.module.css';
 
-// After (default export)
-import styles from './Foo.module.css';
-console.log(styles); // { bright: 'Foo_bright__hash' }
+// Use the camelCase versions in your components
+<button className={myButton} />
 ```
 
-### 3. Debug Webpack Configuration (Optional)
+#### 4. Using a Codemod for Large Codebases
 
-To inspect the final webpack configuration:
+For large codebases, you can create a codemod to automate the migration:
 
-```bash
-NODE_ENV=development bin/shakapacker --profile --json > /tmp/webpack-stats.json
+```js
+// css-modules-v9-migration.js
+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();
+};
 ```
 
-Then search for `css-loader` options in the generated JSON file.
+Run with:
+```bash
+npx jscodeshift -t css-modules-v9-migration.js src/
+```
 
 ---
 
-## Benefits of Default Export Approach
+## Version Comparison
 
-1. **Better Developer Experience**: Matches most React tutorials and documentation
-2. **IDE Support**: Better autocomplete and IntelliSense for CSS class names
-3. **Type Safety**: Easier to add TypeScript definitions for CSS modules
-4. **Consistency**: Aligns with common React ecosystem practices
+| 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) | `camelCase` |
+| TypeScript warnings | May show warnings | No warnings |
+| Tree-shaking | Limited | Optimized |
 
 ---
 
-## Migration Guide
+## Benefits of Named Exports (v9 Default)
 
-If you're migrating from named exports to default exports:
+1. **No Build Warnings**: Eliminates webpack/TypeScript warnings about missing exports
+2. **Better Tree-Shaking**: Unused CSS class exports can be eliminated
+3. **Explicit Dependencies**: Clear about which CSS classes are being used
+4. **Modern Standards**: Aligns with ES modules and modern tooling
+5. **Type Safety**: TypeScript can validate individual class imports
 
-### 1. Update Import Statements
+## Benefits of Default Exports (v8 Behavior)
 
-```js
-// Old (named exports)
-import { bright, container, button } from './Component.module.css';
+1. **Familiar Pattern**: Matches most existing React tutorials
+2. **Namespace Import**: All classes available under one import
+3. **Less Verbose**: Single import for all classes
+4. **Legacy Compatibility**: Works with existing codebases
 
-// New (default export)
-import styles from './Component.module.css';
-```
+---
 
-### 2. Update Class References
+## Verifying the Configuration
 
-```js
-// Old
-<div className={container}>
-  <button className={button}>Click me</button>
-  <span className={bright}>Highlighted text</span>
-</div>
+### 1. Rebuild Your Packs
 
-// New
-<div className={styles.container}>
-  <button className={styles.button}>Click me</button>
-  <span className={styles.bright}>Highlighted text</span>
-</div>
+After making any configuration changes, rebuild your webpack bundles:
+
+```bash
+# For development
+NODE_ENV=development bin/shakapacker
+
+# Or with the dev server
+bin/shakapacker-dev-server
 ```
 
-### 3. Consider Using a Codemod
+### 2. Test in Your React Component
 
-For large codebases, consider writing a codemod to automate the migration:
+Verify your imports work correctly:
 
-```bash
-# Example using jscodeshift (pseudocode)
-npx jscodeshift -t css-modules-migration.js src/
-```
+```js
+// v9 default (named exports)
+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' }
+```
 
-## Future Shakapacker Configuration
+### 3. Debug Webpack Configuration (Optional)
 
-In future versions of Shakapacker, this configuration may be exposed via `config/shakapacker.yml`:
+To inspect the final webpack configuration:
 
-```yml
-# Future configuration (not yet implemented)
-css_modules:
-  # true  -> named exports (import { bright } ...)
-  # false -> default export (import styles ...)
-  named_export: false
+```bash
+NODE_ENV=development bin/shakapacker --profile --json > /tmp/webpack-stats.json
 ```
 
-- **Current behavior:** Uses named exports when unset
-- **Future behavior:** New app templates will default to `false`
-- **Next major release:** The default will change to `false` when unset
+Then search for `css-loader` options in the generated JSON file.
 
 ---
 
@@ -251,15 +370,26 @@ css_modules:
 
 ### CSS Classes Not Applying
 
-If your CSS classes aren't applying after the change:
+If your CSS classes aren't applying after the upgrade:
 
-1. **Check import syntax**: Ensure you're using `import styles from ...`
-2. **Verify class names**: Use `console.log(styles)` to see available classes
-3. **Rebuild webpack**: Clear cache and rebuild: `rm -rf tmp/cache && bin/shakapacker`
+1. **Check import syntax**: Ensure you're using the correct import style for your configuration
+2. **Verify class names**: Use `console.log` to see available classes
+3. **Check camelCase conversion**: Kebab-case names are converted to camelCase in v9
+4. **Rebuild webpack**: Clear cache and rebuild: `rm -rf tmp/cache && bin/shakapacker`
 
 ### TypeScript Support
 
-For TypeScript projects, create type definitions for your CSS modules:
+#### For v9 (Named Exports)
+
+```typescript
+// src/types/css-modules.d.ts
+declare module '*.module.css' {
+  const classes: { [key: string]: string };
+  export = classes;
+}
+```
+
+#### For v8 Behavior (Default Export)
 
 ```typescript
 // src/types/css-modules.d.ts
@@ -281,8 +411,8 @@ The configuration changes should not impact build performance significantly. If
 
 ## Summary
 
-- **Current default**: Named exports (`import { bright } ...`)
-- **Recommended for DX**: Default export (`import styles ...`)
-- **Implementation**: Override CSS loader configuration in `commonWebpackConfig.js`
-- **Migration**: Update imports and class references systematically
-- **Future**: Shakapacker will provide native configuration options
+- **v9 default**: Named exports with camelCase conversion
+- **v8 default**: Default export object with no conversion
+- **Migration path**: Update imports or override configuration
+- **Benefits of v9**: No warnings, better tree-shaking, explicit dependencies
+- **Keeping v8 behavior**: Override css-loader configuration as shown above

data/docs/deployment.md

@@ -88,7 +88,16 @@ Now, you can set `brotli_static on;` in your nginx site config, as per the confi
 
 ## CDN
 
-If you are using a CDN setup, Shakapacker does NOT use the `ASSET_HOST` environment variable to prefix URLs for assets during bundle compilation. You must use the `SHAKAPACKER_ASSET_HOST` environment variable instead (`WEBPACKER_ASSET_HOST` if you're using any version of Webpacker or Shakapacker before Shakapacker v7).
+Shakapacker supports serving JavaScript bundles and assets from a CDN. For a comprehensive guide on setting up CDN with Shakapacker, including CloudFlare configuration, troubleshooting, and advanced setups, see the [CDN Setup Guide](cdn_setup.md).
+
+**Quick Setup**: Set the `SHAKAPACKER_ASSET_HOST` environment variable before compiling assets:
+
+```bash
+export SHAKAPACKER_ASSET_HOST=https://cdn.example.com
+RAILS_ENV=production bundle exec rails 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).
 
 ## Capistrano
 

data/docs/v6_upgrade.md

@@ -101,6 +101,16 @@ _If you're on webpacker v5, follow [how to upgrade to webpacker v6.0.0.rc.6 from
 
 1. Update `webpack-dev-server` to the current version, greater than 4.2, updating `package.json`.
 
+   **Important:** If you encounter the error `[webpack-cli] Invalid options object. Dev Server has been initialized using an options object that does not match the API schema` with an unknown property `_assetEmittingPreviousFiles`, this indicates your webpack-dev-server configuration contains deprecated options. 
+   
+   To resolve this issue:
+   - Ensure you're using webpack-cli >= 4.7.0 with webpack-dev-server 5.x (webpack-cli 4.7+ is compatible with webpack-dev-server v5)
+   - Check your current versions: `npm list webpack-cli webpack-dev-server`
+   - Remove any legacy options like `_assetEmittingPreviousFiles` from your dev-server configuration
+   - Review the [webpack-dev-server migration guide](https://github.com/webpack/webpack-dev-server/blob/master/migration-v5.md) for proper v4 to v5 migration steps
+   
+   See [issue #526](https://github.com/shakacode/shakapacker/issues/526) for more details.
+
 1. Update API usage of the view helpers by changing `javascript_packs_with_chunks_tag` and `stylesheet_packs_with_chunks_tag` to `javascript_pack_tag` and `stylesheet_pack_tag`. Ensure that your layouts and views will only have **at most one call** to `javascript_pack_tag` and **at most one call** to `stylesheet_pack_tag`. You can now pass multiple bundles to these view helper methods. If you fail to changes this, you may experience performance issues, and other bugs related to multiple copies of React, like [issue 2932](https://github.com/rails/webpacker/issues/2932).  If you expose jquery globally with `expose-loader` by using `import $ from "expose-loader?exposes=$,jQuery!jquery"` in your `app/javascript/application.js`, pass the option `defer: false` to your `javascript_pack_tag`.
 
 1. If you are using any integrations like `css`, `postcss`, `React` or `TypeScript`. Please see https://github.com/shakacode/shakapacker#integrations section on how they work in v6.

data/docs/v9_upgrade.md

@@ -0,0 +1,185 @@
+# Shakapacker v9 Upgrade Guide
+
+This guide outlines breaking changes and migration steps for upgrading from Shakapacker v8 to v9.
+
+## Breaking Changes
+
+### 1. CSS Modules Configuration Changed to Named Exports
+
+**What changed:** CSS Modules are now configured with `namedExport: true` and `exportLocalsConvention: 'camelCase'` by default, aligning with Next.js and modern tooling standards.
+
+**JavaScript Projects:**
+```js
+// Before (v8)
+import styles from './Component.module.css';
+<button className={styles.button} />
+
+// After (v9)
+import { button } from './Component.module.css';
+<button className={button} />
+```
+
+**TypeScript Projects:**
+```typescript
+// Before (v8)
+import styles from './Component.module.css';
+<button className={styles.button} />
+
+// After (v9) - namespace import due to TypeScript limitations
+import * as styles from './Component.module.css';
+<button className={styles.button} />
+```
+
+**Migration Options:**
+
+1. **Update your code** (Recommended):
+   - JavaScript: Change to named imports (`import { className }`)
+   - 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
+
+**Benefits of the change:**
+- Eliminates webpack/TypeScript warnings
+- Better tree-shaking of unused CSS classes
+- More explicit about which classes are used
+- Aligns with modern JavaScript standards
+
+### 2. Configuration Option Renamed: `webpack_loader` → `javascript_transpiler`
+
+**What changed:** The configuration option has been renamed to better reflect its purpose.
+
+**Before (v8):**
+```yml
+# config/shakapacker.yml
+webpack_loader: 'babel'
+```
+
+**After (v9):**
+```yml
+# config/shakapacker.yml
+javascript_transpiler: 'babel'
+```
+
+**Note:** The old `webpack_loader` option is deprecated but still supported with a warning.
+
+### 3. Rspack Support Added
+
+**New feature:** Shakapacker v9 adds support for Rspack as an alternative bundler to webpack.
+
+```yml
+# config/shakapacker.yml
+assets_bundler: 'rspack'  # or 'webpack' (default)
+```
+
+## Migration Steps
+
+### Step 1: Update Dependencies
+
+```bash
+npm update shakapacker@^9.0.0
+# or
+yarn upgrade shakapacker@^9.0.0
+```
+
+### Step 2: Update CSS Module Imports
+
+#### For each CSS module import:
+
+```js
+// Find imports like this:
+import styles from './styles.module.css';
+
+// Replace with named imports:
+import { className1, className2 } from './styles.module.css';
+```
+
+#### Update TypeScript definitions:
+
+```typescript
+// Update your CSS module type definitions
+declare module '*.module.css' {
+  // With namedExport: true, css-loader generates individual named exports
+  // TypeScript can't know the exact names at compile time, so we declare
+  // a module with any number of string exports
+  const classes: { readonly [key: string]: string };
+  export = classes;
+  // Note: This allows 'import * as styles' but not 'import styles from'
+  // because css-loader with namedExport: true doesn't generate a default export
+}
+```
+
+### Step 3: Handle Kebab-Case Class Names
+
+v9 automatically converts kebab-case to camelCase:
+
+```css
+/* styles.module.css */
+.my-button { }
+.primary-color { }
+```
+
+```js
+// v9 imports
+import { myButton, primaryColor } from './styles.module.css';
+```
+
+### Step 4: Update Configuration Files
+
+If you have `webpack_loader` in your configuration:
+
+```yml
+# config/shakapacker.yml
+# OLD:
+# webpack_loader: 'babel'
+
+# NEW:
+javascript_transpiler: 'babel'
+```
+
+### Step 5: Run Tests
+
+```bash
+# Run your test suite
+npm test
+
+# Build your application
+bin/shakapacker
+
+# Test in development
+bin/shakapacker-dev-server
+```
+
+## Troubleshooting
+
+### CSS Classes Not Applying
+
+- Ensure you're using named imports: `import { className } from '...'`
+- Check camelCase conversion for kebab-case names
+- Clear cache: `rm -rf tmp/cache && bin/shakapacker`
+
+### TypeScript Errors
+
+Update your global type definitions as shown in Step 2.
+
+### Build Warnings
+
+If you see warnings about CSS module exports, ensure you've updated all imports to use named exports or have properly configured the override.
+
+## Need Help?
+
+- See [CSS Modules Export Mode documentation](./css-modules-export-mode.md) for detailed configuration options
+- Check the [CHANGELOG](../CHANGELOG.md) for all changes
+- File issues at [GitHub Issues](https://github.com/shakacode/shakapacker/issues)
+
+## Gradual Migration Strategy
+
+If you have a large codebase and need to migrate gradually:
+
+1. Override the CSS configuration to keep v8 behavior (see [documentation](./css-modules-export-mode.md))
+2. Migrate files incrementally
+3. Remove the override once migration is complete
+
+This allows you to upgrade to v9 immediately while taking time to update your CSS module imports.

data/lib/install/config/shakapacker.yml

@@ -29,6 +29,10 @@ default: &default
   # Location for manifest.json, defaults to {public_output_path}/manifest.json if unset
   # manifest_path: public/packs/manifest.json
 
+  # Location for private server-side bundles (e.g., for SSR)
+  # These bundles are not served publicly, unlike public_output_path
+  # private_output_path: ssr-generated
+
   # Additional paths webpack should look up modules
   # ['app/assets', 'engine/foo/app/assets']
   additional_paths: []