Add css_modules_export_mode configuration option (#817)

## Summary

Introduces a simple, user-friendly configuration option to control CSS
Modules export mode, making it much easier to restore v8 behavior
without manual webpack configuration overrides.

## Problem Solved

Issue #809 identified that upgrading from Shakapacker v8 to v9 requires
complex webpack configuration overrides to maintain v8 CSS Modules
behavior. This creates a high barrier for teams with large codebases who
need to migrate gradually.

## Solution

Add a `css_modules_export_mode` configuration option to
`shakapacker.yml`:

```yaml
# config/shakapacker.yml
default: &default
  # CSS Modules export mode
  # 'named' (default) - Use named exports with camelCase conversion (v9 default)
  # 'default' - Use default export with both original and camelCase names (v8 behavior)
  css_modules_export_mode: "named"
```

## Changes

1. **Configuration Schema** (`lib/install/config/shakapacker.yml`)
   - Added `css_modules_export_mode` option with clear documentation
   - Defaults to `"named"` to maintain v9 behavior

2. **TypeScript Types** (`package/types.ts`)
- Added `css_modules_export_mode?: "named" | "default"` to Config
interface
   - Provides type safety and IDE autocomplete

3. **Implementation** (`package/utils/getStyleRule.ts`)
   - Reads configuration and applies appropriate CSS loader settings
- `"named"`: Sets `namedExport: true` and `exportLocalsConvention:
"camelCaseOnly"` (v9 default)
- `"default"`: Sets `namedExport: false` and `exportLocalsConvention:
"camelCase"` (v8 behavior)

4. **Documentation Updates**
- Updated `docs/css-modules-export-mode.md` with new configuration
approach
- Updated `docs/v9_upgrade.md` to highlight the simple config option
first
   - Reorganized migration options to emphasize the easiest approach

## Benefits

- **No webpack expertise required** - Users just change one line in YAML
- **Reduced migration friction** - Large codebases can upgrade
immediately
- **Clear migration path** - Simple to enable v8 mode, then gradually
migrate
- **Maintains best practices** - Defaults to v9 behavior, but provides
escape hatch
- **Better than PR #810** - While that PR improved documentation, this
provides a programmatic solution

## Example Usage

### Keeping v8 Behavior
```yaml
# config/shakapacker.yml
css_modules_export_mode: "default"
```

Then continue using v8-style imports:
```javascript
import styles from './Component.module.css';
<button className={styles.button} />
```

### Using v9 Behavior (Default)
```yaml
# config/shakapacker.yml
css_modules_export_mode: "named"  # or omit this line
```

Use v9-style imports:
```javascript
// JavaScript
import { button } from './Component.module.css';
<button className={button} />

// TypeScript
import * as styles from './Component.module.css';
<button className={styles.button} />
```

## Migration Strategy

1. **Immediate upgrade**: Set `css_modules_export_mode: "default"` to
maintain v8 behavior
2. **Gradual migration**: Update components incrementally to use named
exports
3. **Complete migration**: Remove the config option to use v9 default

## Test Plan

- [x] Linting passes (`yarn lint`)
- [x] RuboCop passes (`bundle exec rubocop`)
- [x] TypeScript type checking passes (`yarn run tsc --noEmit`)
- [x] Configuration is properly typed
- [x] Documentation is clear and comprehensive

## Related

- Addresses issue #809
- Complements PR #810 (documentation improvements)
- Supersedes manual webpack configuration approach

Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a configurable CSS Modules export mode allowing projects to use
either v8-style default imports or v9-style named exports.

* **Documentation**
* Expanded upgrade and CSS Modules guides with step-by-step
configuration examples and migration options (easy config-driven or
advanced manual approaches).

* **Tests**
* Updated test coverage to validate mode-dependent CSS Modules behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <[email protected]>

Author: justin808

CHANGELOG.md

@@ -17,6 +17,7 @@ Changes since the last non-beta release.
 
 ### Added
 
+- **Support for `css_modules_export_mode` configuration option**. [PR #817](https://github.com/shakacode/shakapacker/pull/817) by [justin808](https://github.com/justin808). Adds `css_modules_export_mode` setting in `shakapacker.yml` to control CSS Modules export style. Set to `"named"` (default, v9+ behavior with true named exports) or `"default"` (v8 behavior with default export object). Allows teams to opt into v8-style exports for easier migration from v8 or when using TypeScript with strict type checking.
 - **`Configuration#data` public API method** with enhanced documentation and safety. [PR #820](https://github.com/shakacode/shakapacker/pull/820) by [justin808](https://github.com/justin808). The `Configuration#data` method is now part of the public Ruby API, providing stable access to raw configuration data. Returns a frozen hash with symbolized keys to prevent accidental mutations. Includes comprehensive test coverage and detailed RDoc documentation.
 - **Support for `javascript_transpiler: 'none'`** for completely custom webpack configurations. [PR #799](https://github.com/shakacode/shakapacker/pull/799) by [justin808](https://github.com/justin808). Allows users with custom webpack configs to skip Shakapacker's transpiler setup and validation by setting `javascript_transpiler: 'none'` in `shakapacker.yml`. Useful when managing transpilation entirely outside of Shakapacker's defaults.
 

docs/css-modules-export-mode.md

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

docs/v9_upgrade.md

@@ -145,9 +145,18 @@ import * as styles from './Component.module.css';
    - TypeScript: Change to namespace imports (`import * as styles`)
    - Kebab-case class names are automatically converted to camelCase
 
-2. **Keep v8 behavior** temporarily:
+2. **Keep v8 behavior** temporarily using configuration file (Easiest):
+
+   ```yaml
+   # config/shakapacker.yml
+   css_modules_export_mode: default
+   ```
+
+   This allows you to keep using default imports while migrating gradually
+
+3. **Keep v8 behavior** using webpack configuration (Advanced):
    - 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
+   - Provides more control over the configuration
 
 **Benefits of the change:**
 

lib/install/config/shakapacker.yml

@@ -19,6 +19,18 @@ default: &default
   #  css_extract_ignore_order_warnings to true
   css_extract_ignore_order_warnings: false
 
+  # CSS Modules export mode
+  # Controls how CSS Module class names are exported in JavaScript
+  # Defaults to 'named' if not specified. Uncomment and change to 'default' for v8 behavior.
+  # Options:
+  #   - named (default): Use named exports with camelCase conversion (v9 default)
+  #     Example: import { button } from './styles.module.css'
+  #   - default: Use default export with both original and camelCase names (v8 behavior)
+  #     Example: import styles from './styles.module.css'
+  # For gradual migration, you can set this to default to maintain v8 behavior
+  # See https://github.com/shakacode/shakapacker/blob/main/docs/css-modules-export-mode.md
+  # css_modules_export_mode: named
+
   public_root_path: public
   public_output_path: packs
   cache_path: tmp/shakapacker

lib/shakapacker/configuration.rb

@@ -339,6 +339,31 @@ def webpack_loader
     javascript_transpiler
   end
 
+  # Returns the CSS Modules export mode configuration
+  #
+  # Controls how CSS Module class names are exported in JavaScript:
+  # - "named" (default): Use named exports with camelCase conversion (v9 behavior)
+  # - "default": Use default export with both original and camelCase names (v8 behavior)
+  #
+  # @return [String] "named" or "default"
+  # @raise [ArgumentError] if an invalid value is configured
+  def css_modules_export_mode
+    @css_modules_export_mode ||= begin
+      mode = fetch(:css_modules_export_mode) || "named"
+
+      # Validate the configuration value
+      valid_modes = ["named", "default"]
+      unless valid_modes.include?(mode)
+        raise ArgumentError,
+          "Invalid css_modules_export_mode: '#{mode}'. " \
+          "Valid values are: #{valid_modes.map { |m| "'#{m}'" }.join(', ')}. " \
+          "See https://github.com/shakacode/shakapacker/blob/main/docs/css-modules-export-mode.md"
+      end
+
+      mode
+    end
+  end
+
   # Returns the path to the bundler configuration directory
   #
   # This is where webpack.config.js or rspack.config.js should be located.

package/types.ts

@@ -15,6 +15,7 @@ export interface Config {
   source_entry_path: string
   nested_entries: boolean
   css_extract_ignore_order_warnings: boolean
+  css_modules_export_mode?: "named" | "default"
   public_root_path: string
   public_output_path: string
   private_output_path?: string

package/utils/getStyleRule.ts

@@ -29,6 +29,11 @@ const getStyleRule = (
         ? requireOrError("@rspack/core").CssExtractRspackPlugin.loader
         : requireOrError("mini-css-extract-plugin").loader
 
+    // Determine CSS Modules export mode based on configuration
+    // 'named' (default): Use named exports with camelCaseOnly (v9 behavior)
+    // 'default': Use default exports with camelCase (v8 behavior)
+    const useNamedExports = config.css_modules_export_mode !== "default"
+
     const use = [
       inliningCss ? "style-loader" : extractionPlugin,
       {
@@ -38,11 +43,13 @@ const getStyleRule = (
           importLoaders: 2,
           modules: {
             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"
+            // Use named exports for v9 (default), or default exports for v8 compatibility
+            namedExport: useNamedExports,
+            // 'camelCaseOnly' with namedExport: true (v9 default)
+            // 'camelCase' with namedExport: false (v8 behavior - exports both original and camelCase)
+            exportLocalsConvention: useNamedExports
+              ? "camelCaseOnly"
+              : "camelCase"
           }
         }
       },

spec/shakapacker/css_modules_spec.rb

@@ -181,17 +181,57 @@
       # Read the TypeScript source to verify configuration
       style_rule_content = File.read("package/utils/getStyleRule.ts")
 
-      # Should have namedExport: true
-      expect(style_rule_content).to include("namedExport: true")
+      # Should have conditional logic based on css_modules_export_mode
+      expect(style_rule_content).to include("css_modules_export_mode")
+      expect(style_rule_content).to include("useNamedExports")
 
-      # Should have exportLocalsConvention: 'camelCaseOnly' (not 'camelCase')
-      expect(style_rule_content).to include('exportLocalsConvention: "camelCaseOnly"')
+      # Should set namedExport conditionally
+      expect(style_rule_content).to include("namedExport: useNamedExports")
 
-      # Should NOT have the invalid 'camelCase' with namedExport: true
-      expect(style_rule_content).not_to include('exportLocalsConvention: "camelCase"')
+      # Should set exportLocalsConvention conditionally
+      expect(style_rule_content).to include("exportLocalsConvention: useNamedExports")
+      expect(style_rule_content).to include('"camelCaseOnly"')
+      expect(style_rule_content).to include('"camelCase"')
 
-      # Should have explanatory comment about the requirement
-      expect(style_rule_content).to include("css-loader requires 'camelCaseOnly' or 'dashesOnly'")
+      # Should have explanatory comments about v9 and v8 behavior
+      expect(style_rule_content).to include("v9 behavior")
+      expect(style_rule_content).to include("v8 behavior")
+    end
+
+    describe "css_modules_export_mode configuration" do
+      it "defaults to 'named' when not specified" do
+        # The test config doesn't have css_modules_export_mode set
+        expect(config.css_modules_export_mode).to eq("named")
+      end
+
+      it "accepts 'default' as a valid value" do
+        allow(config).to receive(:fetch).with(:css_modules_export_mode).and_return("default")
+        expect(config.css_modules_export_mode).to eq("default")
+      end
+
+      it "raises ArgumentError for invalid values" do
+        allow(config).to receive(:fetch).with(:css_modules_export_mode).and_return("invalid")
+
+        expect {
+          config.css_modules_export_mode
+        }.to raise_error(ArgumentError, /Invalid css_modules_export_mode: 'invalid'/)
+      end
+
+      it "provides helpful error message with valid options" do
+        allow(config).to receive(:fetch).with(:css_modules_export_mode).and_return("foobar")
+
+        expect {
+          config.css_modules_export_mode
+        }.to raise_error(ArgumentError, /Valid values are: 'named', 'default'/)
+      end
+
+      it "includes documentation link in error message" do
+        allow(config).to receive(:fetch).with(:css_modules_export_mode).and_return("bad")
+
+        expect {
+          config.css_modules_export_mode
+        }.to raise_error(ArgumentError, /css-modules-export-mode\.md/)
+      end
     end
   end