shakapacker 9.0.0.beta.8 → 9.0.0.beta.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b968c57e16cafe6ddb6fb317b442db6b96682ee075498f3b8bc60f43f87d7bd
-  data.tar.gz: a3bf4f39a4c6b869e3301723423387577a78a0818403c1bb31efd42f9bc0ac7c
+  metadata.gz: 5bcee4a9f167db64caa92dd26cc09d18b58a7bcd9e42df48d83a67ee588e4661
+  data.tar.gz: 70bee9a11ad197b10731b8f0870c52093fa64092ad470525679d32b44b64fcc2
 SHA512:
-  metadata.gz: ebfa33ceea921c0c66f9a9affb4eb1c736c981696d87523e4a55f82311e6779a28b3b9ca0b8b8a270fb00dbd04302be57928091f4b7c7b580ee66d2585c98f4f
-  data.tar.gz: 61a683b023eec46e7beb3a294db371b28ac1d8668744d7212ab938eb5a0a1fe53dba7763f5f9e90374ed329cb2f6ae07a232f3b0970e3bb4d504f4b79ea9eaeb
+  metadata.gz: 7c3be887fa8da2e9ef41aaf1753556da768002c7fcb0a765d348dac99c49d092caf2fe652008b86059a98c4b62d78326ff5f14cf4e39ed30696aebcd83560bc0
+  data.tar.gz: 2f4e2c8a069381191daed7fa8dbe6a38c93731c31399234d78621448d9a48a9d0759d9f84e29a94e8e87a88e4174e7a52d951470c56779fca673ebdc907fdda9

data/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+npx lint-staged

data/CHANGELOG.md

@@ -9,70 +9,9 @@
 ## [Unreleased]
 Changes since the last non-beta release.
 
-### Added
-- **Phase 5 TypeScript Migration - Framework-Specific Modules** by [justin808](https://github.com/justin808)
-  - Converted framework-specific modules to TypeScript
-  - Migrated package/rspack/index.js to TypeScript
-  - Migrated package/swc/index.js to TypeScript
-  - Migrated package/esbuild/index.js to TypeScript
-  - Migrated package/babel/preset.js to TypeScript
-  - Added @types/babel__core for enhanced type safety
-  - All 130 tests passing
-- **Phase 6 TypeScript Migration - Final Cleanup** (by [justin808](https://github.com/justin808))
-  - Added TypeScript ESLint support with @typescript-eslint/parser and @typescript-eslint/eslint-plugin
-  - Configured TypeScript-specific linting rules for improved code quality
-  - Verified strict mode is enabled in TypeScript configuration
-  - Enhanced developer experience with TypeScript linting across the entire codebase
-
-## [v9.0.0-beta.7] - October 1, 2025
-
-### Added
-- **Phase 2 TypeScript Migration - Core Modules** ([PR 608](https://github.com/shakacode/shakapacker/pull/608) by [justin808](https://github.com/justin808))
-  - Converted core modules to TypeScript: config.ts, env.ts, and utilities
-  - Enhanced type safety across the codebase
-  - Better IDE support and autocomplete
-- **Phase 3 TypeScript Migration - Environment Files** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
-  - Converted all environment configuration files to TypeScript (development, production, test)
-  - Added centralized type exports for consumer use (import from "shakapacker/types")
-  - Created shared TypeScript interfaces for environment configurations
-  - Introduced structured error codes for programmatic error handling
-  - Exported shared types: WebpackConfig, RspackConfig, EnvironmentConfig
-- **Optional Peer Dependencies** ([PR 615](https://github.com/shakacode/shakapacker/pull/615) by [justin808](https://github.com/justin808))
-  - Restored peer dependencies as optional to improve package version tracking
-  - Added peerDependenciesMeta marking all peers as optional
-  - Moved webpack-merge to direct dependencies (required at runtime)
-  - Prevents installation warnings while maintaining upgrade visibility
-- **Migration Tooling Improvements** ([PR 613](https://github.com/shakacode/shakapacker/pull/613) by [justin808](https://github.com/justin808))
-  - Added SWC migration helper: rake shakapacker:migrate:to_swc
-  - Enhanced error messages for missing dependencies
-  - Improved doctor command output
-
-### Security
-- **Path Validation Utilities** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
-  - Added validation to prevent directory traversal attacks
-  - Implemented environment variable sanitization to prevent injection
-  - Enforced strict port validation (reject strings with non-digits)
-  - Added SHAKAPACKER_NPM_PACKAGE path validation (only .tgz/.tar.gz allowed)
-  - Path traversal security checks now run regardless of validation mode
+## [v9.0.0-beta.8] - October 3, 2025
 
-### Changed
-- **Build Process Improvements** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
-  - Environment JS files now generated during npm publish (not committed to git)
-  - Prevents TypeScript source and compiled JS from getting out of sync
-  - Auto-format compiled JavaScript during build process
-  - Enhanced .npmignore to exclude TypeScript sources, include compiled JS
-
-### Performance
-- **Validation Caching** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
-  - Implemented TTL-based validation caching (5s watch, 1min dev, infinite prod)
-  - Made cache TTL configurable via SHAKAPACKER_CACHE_TTL environment variable
-  - Lazy-loaded and cached watch mode detection
-
-### Fixed
-- Fixed clearValidationCache() to actually clear the cache ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
-- Fixed private_output_path configuration edge cases ([PR 604](https://github.com/shakacode/shakapacker/pull/604) by [justin808](https://github.com/justin808))
-
-## [v9.0.0-beta.4] - September 15, 2025
+See the [v9 Upgrade Guide](https://github.com/shakacode/shakapacker/blob/main/docs/v9_upgrade.md) for detailed migration instructions.
 
 ### ⚠️ Breaking Changes
 
@@ -80,7 +19,7 @@ Changes since the last non-beta release.
    - Babel dependencies are no longer included as peer dependencies
    - Improves compilation speed by 20x
    - **Migration for existing projects:**
-     - **Option 1 (Recommended):** Switch to SWC:
+     - **Option 1 (Recommended):** Switch to SWC - Run `rake shakapacker:migrate:to_swc` or manually:
        ```yaml
        # config/shakapacker.yml
        javascript_transpiler: 'swc'
@@ -93,11 +32,9 @@ Changes since the last non-beta release.
        ```
 
 2. **CSS Modules now use named exports by default**
-   - Configured with `namedExport: true` and `exportLocalsConvention: 'camelCase'`
    - **JavaScript:** Use named imports: `import { className } from './styles.module.css'`
    - **TypeScript:** Use namespace imports: `import * as styles from './styles.module.css'`
-   - Default imports (`import styles from '...'`) no longer work
-   - See [CSS Modules Export Mode documentation](./docs/css-modules-export-mode.md) for migration details
+   - To keep the old behavior with default imports, see [CSS Modules Export Mode documentation](./docs/css-modules-export-mode.md) for configuration instructions
 
 3. **Configuration option renamed from `webpack_loader` to `javascript_transpiler`**
    - Better reflects its purpose of configuring JavaScript transpilation
@@ -109,23 +46,26 @@ Changes since the last non-beta release.
   - Faster Rust-based bundling with webpack-compatible APIs
   - Built-in SWC loader and CSS extraction
   - Automatic bundler detection in `bin/shakapacker`
-- **Private output path** for server-side rendering bundles ([PR 592](https://github.com/shakacode/shakapacker/pull/592) by [justin808](https://github.com/justin808))
-  - Configure `private_output_path` for private server bundles
-- **Enhanced TypeScript definitions** ([PR 602](https://github.com/shakacode/shakapacker/pull/602) by [justin808](https://github.com/justin808))
-  - Better IDE support and type safety
-- **`rake shakapacker:doctor` diagnostic command** ([PR 609](https://github.com/shakacode/shakapacker/pull/609) by [justin808](https://github.com/justin808))
-  - Check for configuration issues and missing dependencies
-  - Identify missing loaders that cause build errors
-  - Particularly useful when migrating to v9 where peer dependencies are removed
-  - Detects transpiler-specific issues based on v9 changes
+- **TypeScript type definitions** for improved IDE support and autocomplete
+  - Types available via `import type { WebpackConfig, RspackConfig, EnvironmentConfig } from "shakapacker/types"`
+  - See [TypeScript Documentation](./docs/typescript.md) for migration and usage instructions
+- **Optional peer dependencies** - All peer dependencies now marked as optional, preventing installation warnings while maintaining version compatibility tracking
+- **Private output path** for server-side rendering bundles ([PR 592](https://github.com/shakacode/shakapacker/pull/592))
+  - Configure `private_output_path` for private server bundles separate from public assets
+- **`rake shakapacker:doctor` diagnostic command** to check for configuration issues and missing dependencies
+- **`rake shakapacker:migrate:to_swc`** migration helper to assist with switching from Babel to SWC
 
-### Changed
-- Configuration option renamed from `bundler` to `assets_bundler` (deprecated but supported)
-- **Babel dependencies are now optional** instead of peer dependencies ([PR 603](https://github.com/shakacode/shakapacker/pull/603) by [justin808](https://github.com/justin808))
-  - Installed automatically only when `javascript_transpiler` is set to 'babel'
+### Security
+- **Path Validation Utilities** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
+  - Added validation to prevent directory traversal attacks
+  - Implemented environment variable sanitization to prevent injection
+  - Enforced strict port validation (reject strings with non-digits)
+  - Added SHAKAPACKER_NPM_PACKAGE path validation (only .tgz/.tar.gz allowed)
+  - Path traversal security checks now run regardless of validation mode
 
 ### Fixed
-- Update webpack-dev-server to secure versions (^4.15.2 || ^5.2.2) ([PR 585](https://github.com/shakacode/shakapacker/pull/585) by [justin808](https://github.com/justin808))
+- Fixed private_output_path configuration edge cases ([PR 604](https://github.com/shakacode/shakapacker/pull/604))
+- Updated webpack-dev-server to secure versions (^4.15.2 || ^5.2.2) ([PR 585](https://github.com/shakacode/shakapacker/pull/585))
 
 ## [v8.4.0] - September 8, 2024
 
@@ -547,8 +487,8 @@ Note: [Rubygem is 6.3.0.pre.rc.1](https://rubygems.org/gems/shakapacker/versions
 ## v5.4.3 and prior changes from rails/webpacker
 See [CHANGELOG.md in rails/webpacker (up to v5.4.3)](https://github.com/rails/webpacker/blob/master/CHANGELOG.md)
 
-[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.0.0-beta.4...main
-[v9.0.0-beta.4]: https://github.com/shakacode/shakapacker/compare/v8.4.0...v9.0.0-beta.4
+[Unreleased]: https://github.com/shakacode/shakapacker/compare/v9.0.0-beta.8...main
+[v9.0.0-beta.8]: https://github.com/shakacode/shakapacker/compare/v8.4.0...v9.0.0-beta.8
 [v8.4.0]: https://github.com/shakacode/shakapacker/compare/v8.3.0...v8.4.0
 [v8.3.0]: https://github.com/shakacode/shakapacker/compare/v8.2.0...v8.3.0
 [v8.2.0]: https://github.com/shakacode/shakapacker/compare/v8.1.0...v8.2.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.0.0.beta.8)
+    shakapacker (9.0.0.beta.9)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/README.md

@@ -1,13 +1,14 @@
-# Shakapacker (v8)
+# Shakapacker (v9)
 ---
 
-_🚀 Shakapacker 9.0.0.beta.2 supports [Rspack](https://rspack.rs/)! 10x faster than webpack!_
+_🚀 Shakapacker 9 supports [Rspack](https://rspack.rs/)! 10x faster than webpack!_
 
 ---
 
 _Official, actively maintained successor to [rails/webpacker](https://github.com/rails/webpacker). ShakaCode stands behind the long-term maintenance and development of this project for the Rails community._
 
 * ⚠️ See the [6-stable](https://github.com/shakacode/shakapacker/tree/6-stable) branch for Shakapacker v6.x code and documentation. :warning:
+* **See [V9 Upgrade](./docs/v9_upgrade.md) for upgrading from the v8 release.**
 * See [V8 Upgrade](./docs/v8_upgrade.md) for upgrading from the v7 release.
 * See [V7 Upgrade](./docs/v7_upgrade.md) for upgrading from the v6 release.
 * See [V6 Upgrade](./docs/v6_upgrade.md) for upgrading from v5 or prior v6 releases.

data/TODO_v9.md

@@ -20,12 +20,15 @@ Align with Next.js and modern tooling by using named exports:
   options: {
     modules: {
       namedExport: true,
-      exportLocalsConvention: 'camelCase'
+      exportLocalsConvention: 'camelCaseOnly'  // Must be 'camelCaseOnly' or 'dashesOnly' with namedExport: true
     }
   }
 }
 ```
 
+**Note:** Using `exportLocalsConvention: 'camelCase'` with `namedExport: true` will cause a build error.
+css-loader only allows `'camelCaseOnly'` or `'dashesOnly'` when named exports are enabled.
+
 2. **Update TypeScript types:**
 - Ensure proper typing for CSS modules with named exports
 - May need to update or generate `.d.ts` files for CSS modules
@@ -81,4 +84,4 @@ Align with Next.js and modern tooling by using named exports:
 ### Test Infrastructure
 - Successfully implemented dual bundler support (webpack/rspack)
 - test-bundler script working well with status command
-- Consider adding more comprehensive tests for both bundlers
+- Consider adding more comprehensive tests for both bundlers

data/conductor-setup.sh

@@ -35,6 +35,18 @@ $BUNDLE_CMD install
 echo "📦 Installing JavaScript dependencies..."
 yarn install
 
+# Set up Husky git hooks
+echo "🪝 Setting up Husky git hooks..."
+npx husky
+if [ ! -f .husky/pre-commit ]; then
+    echo "Creating pre-commit hook..."
+    cat > .husky/pre-commit << 'EOF'
+#!/usr/bin/env sh
+npx lint-staged
+EOF
+    chmod +x .husky/pre-commit
+fi
+
 # Copy environment files if they exist in root
 if [ -n "${CONDUCTOR_ROOT_PATH:-}" ]; then
     if [ -f "$CONDUCTOR_ROOT_PATH/.env" ]; then

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

@@ -32,6 +32,55 @@ import * as styles from './Foo.module.css';
 - Aligns with modern JavaScript module standards
 - Automatically converts kebab-case to camelCase (`my-button` → `myButton`)
 
+### Important: exportLocalsConvention with namedExport
+
+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,
+  exportLocalsConvention: 'camelCase'  // ❌ ERROR: incompatible with namedExport: true
+}
+```
+
+**Error message:**
+```
+"exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option
+```
+
+**Correct v9 configuration:**
+```js
+modules: {
+  namedExport: true,
+  exportLocalsConvention: 'camelCaseOnly'  // ✅ Correct - only camelCase exported
+}
+```
+
+**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 |
+
+**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
+
 ## Version 8.x and Earlier Behavior
 
 In Shakapacker v8 and earlier, the default behavior was to use a **default export object**:
@@ -244,7 +293,9 @@ import { bright, container, button } from './Component.module.css';
 
 #### 3. Handle Kebab-Case Class Names
 
-With v9's `exportLocalsConvention: 'camelCase'`, kebab-case class names are automatically converted:
+**Option A: Use camelCase (v9 default)**
+
+With `exportLocalsConvention: 'camelCaseOnly'`, kebab-case class names are automatically converted:
 
 ```css
 /* styles.module.css */
@@ -253,13 +304,35 @@ With v9's `exportLocalsConvention: 'camelCase'`, kebab-case class names are auto
 ```
 
 ```js
-// v9 imports (camelCase conversion)
+// v9 default - camelCase conversion
 import { myButton, primaryColor } from './styles.module.css';
+<button className={myButton} />
+```
 
-// Use the camelCase versions in your components
+**Option B: Keep kebab-case with 'dashesOnly'**
+
+If you prefer to preserve the original kebab-case names, configure your webpack to use `'dashesOnly'`:
+
+```js
+// config/webpack/commonWebpackConfig.js
+modules: {
+  namedExport: true,
+  exportLocalsConvention: 'dashesOnly'
+}
+```
+
+```js
+// With dashesOnly - preserve kebab-case
+import * as styles from './styles.module.css';
+<button className={styles['my-button']} />
+
+// Or with aliasing:
+import { 'my-button': myButton } from './styles.module.css';
 <button className={myButton} />
 ```
 
+**Note:** With both `'camelCaseOnly'` and `'dashesOnly'`, only one version of each class name is exported. The original kebab-case name is NOT available with `'camelCaseOnly'`, and the camelCase version is NOT available with `'dashesOnly'`.
+
 #### 4. Using a Codemod for Large Codebases
 
 For large codebases, you can create a codemod to automate the migration:
@@ -298,12 +371,12 @@ npx jscodeshift -t css-modules-v9-migration.js src/
 
 ## Version Comparison
 
-| Feature | v8 (and earlier) | v9 | 
-|---------|-----------------|----| 
+| 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` |
+| Export convention | `asIs` (no transformation) | `camelCaseOnly` |
 | TypeScript warnings | May show warnings | No warnings |
 | Tree-shaking | Limited | Optimized |
 
@@ -368,13 +441,34 @@ Then search for `css-loader` options in the generated JSON file.
 
 ## Troubleshooting
 
+### Build Error: exportLocalsConvention Incompatible with namedExport
+
+If you see this error during build:
+```
+"exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option
+```
+
+**Cause:** Your webpack configuration has `namedExport: true` with `exportLocalsConvention: 'camelCase'`.
+
+**Solution:** Change `exportLocalsConvention` to `'camelCaseOnly'` or `'dashesOnly'`:
+
+```js
+// config/webpack/commonWebpackConfig.js or similar
+modules: {
+  namedExport: true,
+  exportLocalsConvention: 'camelCaseOnly'  // or 'dashesOnly'
+}
+```
+
+Alternatively, if you need the `'camelCase'` option (both original and camelCase exports), you must revert to v8 behavior by setting `namedExport: false` as shown in the "Reverting to Default Exports" section above.
+
 ### CSS Classes Not Applying
 
 If your CSS classes aren't applying after the upgrade:
 
 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
+3. **Check camelCase conversion**: Kebab-case names are converted to camelCase in v9 with `'camelCaseOnly'`
 4. **Rebuild webpack**: Clear cache and rebuild: `rm -rf tmp/cache && bin/shakapacker`
 
 ### TypeScript Support
@@ -415,4 +509,4 @@ The configuration changes should not impact build performance significantly. If
 - **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
+- **Keeping v8 behavior**: Override css-loader configuration as shown above

data/docs/v9_upgrade.md

@@ -19,7 +19,18 @@ See the [TypeScript Documentation](./typescript.md) for usage examples.
 
 ### 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.
+**What changed:** CSS Modules are now configured with `namedExport: true` and `exportLocalsConvention: 'camelCaseOnly'` by default, aligning with Next.js and modern tooling standards.
+
+> **Important:** When `namedExport: true` is enabled, css-loader requires `exportLocalsConvention` to be either `'camelCaseOnly'` or `'dashesOnly'`. Using `'camelCase'` will cause a build error: `"exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option`.
+
+**Quick Reference: Configuration Options**
+
+| Configuration | namedExport | exportLocalsConvention | CSS: `.my-button` | Export Available | Works With |
+|---------------|-------------|------------------------|-------------------|------------------|------------|
+| **v9 Default** | `true` | `'camelCaseOnly'` | `.my-button` | `myButton` only | ✅ Named exports |
+| **Alternative** | `true` | `'dashesOnly'` | `.my-button` | `'my-button'` only | ✅ Named exports |
+| **v8 Style** | `false` | `'camelCase'` | `.my-button` | Both `myButton` AND `'my-button'` | ✅ Default export |
+| **❌ Invalid** | `true` | `'camelCase'` | - | - | ❌ Build Error |
 
 **JavaScript Projects:**
 ```js
@@ -198,7 +209,7 @@ declare module '*.module.css' {
 
 ### Step 3: Handle Kebab-Case Class Names
 
-v9 automatically converts kebab-case to camelCase:
+v9 automatically converts kebab-case to camelCase with `exportLocalsConvention: 'camelCaseOnly'`:
 
 ```css
 /* styles.module.css */
@@ -207,10 +218,34 @@ v9 automatically converts kebab-case to camelCase:
 ```
 
 ```js
-// v9 imports
+// v9 default - camelCase conversion
 import { myButton, primaryColor } from './styles.module.css';
 ```
 
+**Alternative: Keep kebab-case names with 'dashesOnly'**
+
+If you prefer to keep kebab-case names in JavaScript, you can override the configuration to use `'dashesOnly'`:
+
+```js
+// config/webpack/commonWebpackConfig.js
+modules: {
+  namedExport: true,
+  exportLocalsConvention: 'dashesOnly'  // Keep original kebab-case names
+}
+```
+
+Then use the original kebab-case names in your imports:
+
+```js
+// With dashesOnly configuration
+import { 'my-button': myButton, 'primary-color': primaryColor } from './styles.module.css';
+// or access as properties
+import * as styles from './styles.module.css';
+const buttonClass = styles['my-button'];
+```
+
+**Note:** With `'camelCaseOnly'` (default) or `'dashesOnly'`, only one version is exported. If you need both the original and camelCase versions, you would need to use `'camelCase'` instead, but this requires `namedExport: false` (v8 behavior). See the [CSS Modules Export Mode documentation](./css-modules-export-mode.md) for details on reverting to v8 behavior.
+
 ### Step 4: Update Configuration Files
 
 If you have `webpack_loader` in your configuration:
@@ -253,6 +288,25 @@ Update your global type definitions as shown in Step 2.
 
 If you see warnings about CSS module exports, ensure you've updated all imports to use named exports or have properly configured the override.
 
+### Build Error: exportLocalsConvention Incompatible with namedExport
+
+If you see this error:
+```
+"exportLocalsConvention" with "camelCase" value is incompatible with "namedExport: true" option
+```
+
+This means your webpack configuration has `namedExport: true` with `exportLocalsConvention: 'camelCase'`. The fix is to change to `'camelCaseOnly'` or `'dashesOnly'`:
+
+```js
+// config/webpack/commonWebpackConfig.js or wherever you configure css-loader
+modules: {
+  namedExport: true,
+  exportLocalsConvention: 'camelCaseOnly'  // or 'dashesOnly'
+}
+```
+
+If you want to use `'camelCase'` (which exports both original and camelCase versions), you must set `namedExport: false` and revert to v8 behavior. See the [CSS Modules Export Mode documentation](./css-modules-export-mode.md) for details.
+
 ### Unexpected Peer Dependency Warnings After Upgrade
 
 If you experience unexpected peer dependency warnings after upgrading to v9, you may need to clear your package manager's cache and reinstall dependencies. This ensures the new optional peer dependency configuration takes effect properly.

data/lib/shakapacker/doctor.rb

@@ -43,6 +43,7 @@ module Shakapacker
         # Dependency checks
         check_javascript_transpiler_dependencies if config_exists?
         check_css_dependencies
+        check_css_modules_configuration
         check_bundler_dependencies if config_exists?
         check_file_type_dependencies if config_exists?
         check_sri_dependencies if config_exists?
@@ -432,6 +433,28 @@ module Shakapacker
         if transpiler == "esbuild" && package_installed?("babel-loader")
           @warnings << "Both esbuild and Babel dependencies are installed. Consider removing Babel dependencies to reduce node_modules size"
         end
+
+        # Check for SWC configuration conflicts
+        if transpiler == "swc"
+          check_swc_config_conflicts
+        end
+      end
+
+      def check_swc_config_conflicts
+        swcrc_path = root_path.join(".swcrc")
+        return unless swcrc_path.exist?
+
+        begin
+          swcrc = JSON.parse(File.read(swcrc_path))
+          # Check for conflicting jsc.target and env settings
+          if swcrc.dig("jsc", "target") && swcrc["env"]
+            @issues << "SWC configuration conflict: .swcrc contains both 'jsc.target' and 'env' settings, which are mutually exclusive. Remove 'jsc.target' from .swcrc"
+          elsif swcrc.dig("jsc", "target")
+            @warnings << "SWC configuration: .swcrc contains 'jsc.target' which may conflict with the loader's 'env' setting. Consider removing 'jsc.target' from .swcrc to avoid build errors"
+          end
+        rescue JSON::ParserError
+          @warnings << "SWC configuration: .swcrc exists but contains invalid JSON"
+        end
       end
 
       def check_css_dependencies
@@ -440,6 +463,77 @@ module Shakapacker
         check_optional_dependency("mini-css-extract-plugin", @warnings, "CSS extraction")
       end
 
+      def check_css_modules_configuration
+        # Check for CSS module files in the project
+        return unless config_exists?
+
+        source_path = config.source_path
+        return unless source_path.exist?
+
+        # Performance optimization: Just check if ANY CSS module file exists
+        # Using .first with early return is much faster than globbing all files
+        css_module_exists = Dir.glob(File.join(source_path, "**/*.module.{css,scss,sass}")).first
+        return unless css_module_exists
+
+        # Check webpack configuration for CSS modules settings
+        webpack_config_paths = [
+          root_path.join("config/webpack/webpack.config.js"),
+          root_path.join("config/webpack/webpack.config.ts"),
+          root_path.join("config/webpack/commonWebpackConfig.js"),
+          root_path.join("config/webpack/commonWebpackConfig.ts")
+        ]
+
+        webpack_config_paths.each do |config_path|
+          next unless config_path.exist?
+
+          config_content = File.read(config_path)
+
+          # Check for the invalid configuration: namedExport: true with exportLocalsConvention: 'camelCase'
+          if config_content.match(/namedExport\s*:\s*true/) && config_content.match(/exportLocalsConvention\s*:\s*['"]camelCase['"]/)
+            @issues << "CSS Modules: Invalid configuration detected in #{config_path.relative_path_from(root_path)}"
+            @issues << "  Using exportLocalsConvention: 'camelCase' with namedExport: true will cause build errors"
+            @issues << "  Change to 'camelCaseOnly' or 'dashesOnly'. See docs/v9_upgrade.md for details"
+          end
+
+          # Warn if CSS modules are used but no configuration is found
+          if !config_content.match(/namedExport/) && !config_content.match(/exportLocalsConvention/)
+            @info << "CSS module files found but no explicit CSS modules configuration detected"
+            @info << "  v9 defaults: namedExport: true, exportLocalsConvention: 'camelCaseOnly'"
+          end
+        end
+
+        # Check for common v8 to v9 migration issues
+        check_css_modules_import_patterns
+      rescue => e
+        # Don't fail doctor if CSS modules check has issues
+        @warnings << "Unable to validate CSS modules configuration: #{e.message}"
+      end
+
+      def check_css_modules_import_patterns
+        # Look for JavaScript/TypeScript files that might have v8-style imports
+        source_path = config.source_path
+
+        # Use lazy evaluation with Enumerator to avoid loading all file paths into memory
+        # Stop after checking 50 files or finding a match
+        v8_pattern = /import\s+\w+\s+from\s+['"][^'"]*\.module\.(css|scss|sass)['"]/
+
+        Dir.glob(File.join(source_path, "**/*.{js,jsx,ts,tsx}")).lazy.take(50).each do |file|
+          # Read file and check for v8 pattern
+          content = File.read(file)
+
+          # Check for v8 default import pattern with .module.css
+          if v8_pattern.match?(content)
+            @warnings << "Potential v8-style CSS module imports detected (using default import)"
+            @warnings << "  v9 uses named exports. Update to: import { className } from './styles.module.css'"
+            @warnings << "  Or use: import * as styles from './styles.module.css' (TypeScript)"
+            @warnings << "  See docs/v9_upgrade.md for migration guide"
+            break  # Stop after finding first occurrence
+          end
+        end
+      rescue => e
+        # Don't fail doctor if import pattern check has issues
+      end
+
       def check_bundler_dependencies
         bundler = config.assets_bundler
         case bundler

data/lib/shakapacker/swc_migrator.rb

@@ -30,6 +30,15 @@ module Shakapacker
       "swc-loader" => "^0.2.6"
     }.freeze
 
+    ESLINT_CONFIG_FILES = %w[
+      .eslintrc
+      .eslintrc.js
+      .eslintrc.cjs
+      .eslintrc.yaml
+      .eslintrc.yml
+      .eslintrc.json
+    ].freeze
+
     DEFAULT_SWCRC_CONFIG = {
       "jsc" => {
         "parser" => {
@@ -41,8 +50,7 @@ module Shakapacker
           "react" => {
             "runtime" => "automatic"
           }
-        },
-        "target" => "es2015"
+        }
       },
       "module" => {
         "type" => "es6"
@@ -67,6 +75,10 @@ module Shakapacker
       logger.info "🎉 Migration to SWC complete!"
       logger.info "   Note: SWC is approximately 20x faster than Babel for transpilation."
       logger.info "   Please test your application thoroughly after migration."
+      logger.info "\n📝 Configuration Info:"
+      logger.info "   - .swcrc provides base configuration for all environments"
+      logger.info "   - The SWC loader adds automatic environment targeting (via 'env' setting)"
+      logger.info "   - You can customize .swcrc, but avoid setting 'jsc.target' as it conflicts with 'env'"
 
       # Show cleanup recommendations if babel packages found
       if results[:babel_packages_found].any?
@@ -99,6 +111,16 @@ module Shakapacker
         return { removed_packages: [], config_files_deleted: [] }
       end
 
+      # Check if ESLint uses Babel parser
+      if eslint_uses_babel?
+        logger.info "\n⚠️  WARNING: ESLint configuration detected that may use Babel"
+        logger.info "   If you use @babel/eslint-parser or babel-eslint, you may need to:"
+        logger.info "   1. Keep @babel/core and related Babel packages for ESLint"
+        logger.info "   2. Or switch to @typescript-eslint/parser for TypeScript files"
+        logger.info "   3. Or use espree (ESLint's default parser) for JavaScript files"
+        logger.info "\n   Proceeding with Babel package removal. Check your ESLint config after."
+      end
+
       removed_packages = remove_babel_from_package_json(package_json_path)
       deleted_files = delete_babel_config_files
 
@@ -132,6 +154,42 @@ module Shakapacker
 
     private
 
+      def eslint_uses_babel?
+        # Check for ESLint config files
+        # Note: This is a heuristic check that may have false positives (e.g., in comments),
+        # but false positives only result in an extra warning, which is safer than silently
+        # breaking ESLint configurations.
+        ESLINT_CONFIG_FILES.each do |config_file|
+          config_path = root_path.join(config_file)
+          next unless config_path.exist?
+
+          content = File.read(config_path)
+          # Check for Babel parser references
+          return true if content.match?(/@babel\/eslint-parser|babel-eslint/)
+        end
+
+        # Check package.json for eslintConfig
+        package_json_path = root_path.join("package.json")
+        if package_json_path.exist?
+          begin
+            package_json = JSON.parse(File.read(package_json_path))
+            if package_json["eslintConfig"]
+              return true if package_json["eslintConfig"].to_json.match?(/@babel\/eslint-parser|babel-eslint/)
+            end
+
+            # Check if Babel ESLint packages are installed
+            dependencies = package_json["dependencies"] || {}
+            dev_dependencies = package_json["devDependencies"] || {}
+            all_deps = dependencies.merge(dev_dependencies)
+            return true if all_deps.key?("@babel/eslint-parser") || all_deps.key?("babel-eslint")
+          rescue JSON::ParserError => e
+            logger.debug "Could not parse package.json for ESLint detection: #{e.message}"
+          end
+        end
+
+        false
+      end
+
       def update_shakapacker_config
         config_path = root_path.join("config/shakapacker.yml")
         return false unless config_path.exist?

data/lib/shakapacker/version.rb

@@ -1,4 +1,4 @@
 module Shakapacker
   # Change the version in package.json too, please!
-  VERSION = "9.0.0.beta.8".freeze
+  VERSION = "9.0.0.beta.9".freeze
 end

data/package/utils/getStyleRule.ts

@@ -33,7 +33,12 @@ const getStyleRule = (test: RegExp, preprocessors: any[] = []): StyleRule | null
           sourceMap: true,
           importLoaders: 2,
           modules: {
-            auto: true
+            auto: true,
+            // v9 defaults: Use named exports with camelCase conversion
+            // Note: css-loader requires 'camelCaseOnly' or 'dashesOnly' when namedExport is true
+            // Using 'camelCase' with namedExport: true causes a build error
+            namedExport: true,
+            exportLocalsConvention: 'camelCaseOnly'
           }
         }
       },
@@ -56,4 +61,4 @@ const getStyleRule = (test: RegExp, preprocessors: any[] = []): StyleRule | null
   return null
 }
 
-export = { getStyleRule }
+export = { getStyleRule }

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "9.0.0-beta.8",
+  "version": "9.0.0-beta.9",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {

data/tools/README.md

@@ -104,7 +104,7 @@ const Button: React.FC = () => {
 
 ### Notes
 
-1. **Kebab-case conversion**: CSS classes with kebab-case (e.g., `my-button`) are automatically converted to camelCase (`myButton`) for JavaScript files, matching css-loader's `exportLocalsConvention: 'camelCase'` setting.
+1. **Kebab-case conversion**: CSS classes with kebab-case (e.g., `my-button`) are automatically converted to camelCase (`myButton`) for JavaScript files, matching css-loader's `exportLocalsConvention: 'camelCaseOnly'` setting.
 
 2. **Unused imports**: The codemod only imports CSS classes that are actually used in JavaScript files. If you pass the entire styles object to a component, it will convert to namespace import for safety.
 
@@ -121,4 +121,4 @@ const Button: React.FC = () => {
 **Solution**: Ensure your TypeScript definitions are updated as shown in the [v9 Upgrade Guide](../docs/v9_upgrade.md).
 
 **Issue**: Runtime errors about missing CSS classes
-**Solution**: Check if you have kebab-case class names that need camelCase conversion.
+**Solution**: Check if you have kebab-case class names that need camelCase conversion.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakapacker
 version: !ruby/object:Gem::Version
-  version: 9.0.0.beta.8
+  version: 9.0.0.beta.9
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -147,6 +147,7 @@ files:
 - ".github/workflows/ruby.yml"
 - ".github/workflows/test-bundlers.yml"
 - ".gitignore"
+- ".husky/pre-commit"
 - ".node-version"
 - ".npmignore"
 - ".rspec"
@@ -346,7 +347,7 @@ homepage: https://github.com/shakacode/shakapacker
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.0.0.beta.8
+  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.0.0.beta.9
 rdoc_options: []
 require_paths:
 - lib