shakapacker 9.0.0.beta.0 → 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/rspack.md

@@ -1,6 +1,6 @@
 # Rspack Integration
 
-Shakapacker supports [Rspack](https://rspack.rs) as an alternative bundler to Webpack. Rspack is a fast Rust-based web bundler with webpack-compatible API that can significantly speed up your build times.
+Shakapacker supports [Rspack](https://rspack.rs) as an alternative assets bundler to Webpack. Rspack is a fast Rust-based web bundler with webpack-compatible API that can significantly speed up your build times.
 
 ## Installation
 
@@ -25,10 +25,10 @@ To enable Rspack, update your `config/shakapacker.yml`:
 ```yaml
 default: &default
   # ... other config options
-  bundler: 'rspack'  # Change from 'webpack' to 'rspack'
+  assets_bundler: 'rspack'  # Change from 'webpack' to 'rspack'
 ```
 
-## Configuration
+### Configuration Files
 
 Rspack uses its own configuration directory to keep things organized. Create your Rspack configuration file at `config/rspack/rspack.config.js`:
 
@@ -73,7 +73,7 @@ const { generateRspackConfig } = require('shakapacker/rspack')
 module.exports = generateRspackConfig()
 ```
 
-> **Note:** Shakapacker will show a deprecation warning if you use `config/webpack/webpack.config.js` with `bundler: 'rspack'`. Please migrate to `config/rspack/rspack.config.js`.
+> **Note:** Shakapacker will show a deprecation warning if you use `config/webpack/webpack.config.js` with `assets_bundler: 'rspack'`. Please migrate to `config/rspack/rspack.config.js`.
 
 ## Key Differences from Webpack
 
@@ -119,10 +119,10 @@ optimization: {
 All existing Shakapacker commands work the same way and automatically use Rspack when configured:
 
 ```bash
-# Build (automatically uses rspack when bundler: 'rspack')
+# Build (automatically uses rspack when assets_bundler: 'rspack')
 ./bin/shakapacker
 
-# Development server (automatically uses rspack when bundler: 'rspack')  
+# Development server (automatically uses rspack when assets_bundler: 'rspack')
 ./bin/shakapacker-dev-server
 
 # Watch mode
@@ -151,7 +151,7 @@ Rspack typically provides:
    ```yaml
    # config/shakapacker.yml
    default: &default
-     bundler: 'rspack'
+     assets_bundler: 'rspack'
    ```
 
 3. **Create Rspack config:**