shakapacker 8.4.0 → 9.0.0

data/docs/v9_upgrade.md

@@ -0,0 +1,413 @@
+# Shakapacker v9 Upgrade Guide
+
+This guide outlines new features, breaking changes, and migration steps for upgrading from Shakapacker v8 to v9.
+
+## New Features
+
+### TypeScript Support
+
+Shakapacker v9 includes TypeScript definitions for better IDE support and type safety.
+
+- **No breaking changes** - JavaScript configs continue to work
+- **Optional** - Use TypeScript only if you want it
+- **Type safety** - Catch configuration errors at compile-time
+- **IDE support** - Full autocomplete for all options
+
+See the [TypeScript Documentation](./typescript.md) for usage examples.
+
+### NODE_ENV Default Behavior Fixed
+
+**What changed:** NODE_ENV now intelligently defaults based on RAILS_ENV instead of always defaulting to "production".
+
+**New behavior:**
+
+- When `RAILS_ENV=production` → `NODE_ENV` defaults to `"production"`
+- When `RAILS_ENV=development` or unset → `NODE_ENV` defaults to `"development"`
+- When `RAILS_ENV` is any other value (test, staging, etc.) → `NODE_ENV` defaults to `"development"`
+
+**Benefits:**
+
+- **Dev server "just works"** - No need to explicitly set NODE_ENV when running the development server
+- **Correct configuration loaded** - Development server now properly loads the development configuration from shakapacker.yml
+- **Fixes port issues** - Dev server uses the configured port (e.g., 3035) instead of defaulting to 8080
+- **Fixes 404 errors** - Assets load correctly without requiring manual NODE_ENV configuration
+
+**No action required** - This change improves the default behavior and requires no migration.
+
+**If you previously worked around this bug**, you can now remove these workarounds:
+
+- Remove `NODE_ENV=development` from your `.env`, `.env.development`, or `.env.local` files
+- Remove `NODE_ENV=development` from your `docker-compose.yml` or Dockerfile
+- Remove custom scripts that set NODE_ENV before running the dev server
+- Remove `NODE_ENV=development` from your `bin/dev` or Procfile.dev
+
+## Breaking Changes
+
+### 1. CSS Modules Configuration Changed to Named Exports
+
+**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
+// 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. SWC is Now the Default JavaScript Transpiler
+
+**What changed:** SWC replaces Babel as the default JavaScript transpiler. Babel is no longer included in peer dependencies.
+
+**Why:** SWC is 20x faster than Babel while maintaining compatibility with most JavaScript and TypeScript code.
+
+**Impact on existing projects:**
+
+- Your project will continue using Babel if you already have babel packages in package.json
+- To switch to SWC for better performance, see migration options below
+
+**Impact on new projects:**
+
+- New installations will use SWC by default
+- Babel dependencies won't be installed unless explicitly configured
+
+### Migration Options
+
+#### Option 1 (Recommended): Switch to SWC
+
+```yml
+# config/shakapacker.yml
+javascript_transpiler: "swc"
+```
+
+Then install SWC:
+
+```bash
+npm install @swc/core swc-loader
+```
+
+#### Option 2: Keep using Babel
+
+```yml
+# config/shakapacker.yml
+javascript_transpiler: "babel"
+```
+
+No other changes needed - your existing babel packages will continue to work.
+
+#### Option 3: Use esbuild
+
+```yml
+# config/shakapacker.yml
+javascript_transpiler: "esbuild"
+```
+
+Then install esbuild:
+
+```bash
+npm install esbuild esbuild-loader
+```
+
+### 4. 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)
+```
+
+### 5. All Peer Dependencies Now Optional
+
+**What changed:** All peer dependencies are now marked as optional via `peerDependenciesMeta`.
+
+**Benefits:**
+
+- **No installation warnings** - You won't see peer dependency warnings for packages you don't use
+- **Install only what you need** - Using webpack? Don't install rspack. Using SWC? Don't install Babel.
+- **Clear version constraints** - When you do install a package, version compatibility is still enforced
+
+**What this means for you:**
+
+- **Existing projects:** No changes needed. Your existing dependencies will continue to work.
+- **New projects:** The installer only adds the packages you actually need based on your configuration.
+- **Package manager behavior:** npm, yarn, and pnpm will no longer warn about missing peer dependencies.
+
+**Example:** If you're using SWC with webpack, you only need:
+
+```json
+{
+  "dependencies": {
+    "shakapacker": "^9.0.0",
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0",
+    "webpack": "^5.76.0",
+    "webpack-cli": "^5.0.0",
+    "webpack-dev-server": "^5.0.0"
+  }
+}
+```
+
+You won't get warnings about missing Babel, Rspack, or esbuild packages.
+
+## 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 with `exportLocalsConvention: 'camelCaseOnly'`:
+
+```css
+/* styles.module.css */
+.my-button {
+}
+.primary-color {
+}
+```
+
+```js
+// 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:
+
+```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.
+
+### 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.
+
+**For npm:**
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+**For Yarn:**
+
+```bash
+rm -rf node_modules yarn.lock
+yarn install
+```
+
+**For pnpm:**
+
+```bash
+rm -rf node_modules pnpm-lock.yaml
+pnpm install
+```
+
+**For Bun:**
+
+```bash
+rm -rf node_modules bun.lockb
+bun install
+```
+
+**When is this necessary?**
+
+- If you see peer dependency warnings for packages you don't use (e.g., warnings about Babel when using SWC)
+- If your package manager cached the old dependency resolution from v8
+- After switching transpilers or bundlers (e.g., from Babel to SWC, or webpack to rspack)
+
+**Note:** This is typically only needed once after the v8 → v9 upgrade. Subsequent installs will use the correct dependency resolution.
+
+## 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/bin/shakapacker

@@ -2,12 +2,10 @@
 
 ENV["RAILS_ENV"] ||= "development"
 ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["APP_ROOT"] ||= File.expand_path("..", __dir__)
 
 require "bundler/setup"
 require "shakapacker"
-require "shakapacker/webpack_runner"
+require "shakapacker/runner"
 
-APP_ROOT = File.expand_path("..", __dir__)
-Dir.chdir(APP_ROOT) do
-  Shakapacker::WebpackRunner.run(ARGV)
-end
+Shakapacker::Runner.run(ARGV)

data/lib/install/config/rspack/rspack.config.js

@@ -0,0 +1,6 @@
+// See the shakacode/shakapacker README and docs directory for advice on customizing your rspackConfig.
+const { generateRspackConfig } = require('shakapacker/rspack')
+
+const rspackConfig = generateRspackConfig()
+
+module.exports = rspackConfig

data/lib/install/config/rspack/rspack.config.ts

@@ -0,0 +1,7 @@
+// See the shakacode/shakapacker README and docs directory for advice on customizing your rspackConfig.
+import { generateRspackConfig } from 'shakapacker/rspack'
+import type { RspackOptions } from '@rspack/core'
+
+const rspackConfig: RspackOptions = generateRspackConfig()
+
+export default rspackConfig

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: []
@@ -36,8 +40,14 @@ default: &default
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false
 
-  # Select loader to use, available options are 'babel' (default), 'swc' or 'esbuild'
-  webpack_loader: 'babel'
+  # Select JavaScript transpiler to use
+  # Available options: 'swc' (default, 20x faster), 'babel', or 'esbuild'
+  # Note: When using rspack, swc is used automatically regardless of this setting
+  javascript_transpiler: 'swc'
+
+  # Select assets bundler to use
+  # Available options: 'webpack' (default) or 'rspack'
+  assets_bundler: 'webpack'
 
   # Raises an error if there is a mismatch in the shakapacker gem and npm package being used
   ensure_consistent_versioning: true

data/lib/install/config/webpack/webpack.config.ts

@@ -0,0 +1,7 @@
+// See the shakacode/shakapacker README and docs directory for advice on customizing your webpackConfig.
+import { generateWebpackConfig } from 'shakapacker'
+import type { Configuration } from 'webpack'
+
+const webpackConfig: Configuration = generateWebpackConfig()
+
+export default webpackConfig

data/lib/install/package.json

@@ -0,0 +1,38 @@
+{
+  "rspack": {
+    "@rspack/cli": "^1.0.0",
+    "@rspack/core": "^1.0.0",
+    "rspack-manifest-plugin": "^5.0.0"
+  },
+  "webpack": {
+    "mini-css-extract-plugin": "^2.0.0",
+    "terser-webpack-plugin": "^5.3.1",
+    "webpack": "^5.76.0",
+    "webpack-assets-manifest": "^5.0.6 || ^6.0.0",
+    "webpack-cli": "^4.9.2 || ^5.0.0 || ^6.0.0",
+    "webpack-dev-server": "^4.15.2 || ^5.2.2",
+    "webpack-merge": "^5.8.0 || ^6.0.0",
+    "webpack-subresource-integrity": "^5.1.0"
+  },
+  "common": {
+    "compression-webpack-plugin": "^9.0.0 || ^10.0.0|| ^11.0.0",
+    "css-loader": "^6.0.0 || ^7.0.0",
+    "sass-loader": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0",
+    "style-loader": "^3.0.0 || ^4.0.0"
+  },
+  "babel": {
+    "@babel/core": "^7.17.9",
+    "@babel/plugin-transform-runtime": "^7.17.0",
+    "@babel/preset-env": "^7.16.11",
+    "@babel/runtime": "^7.17.9",
+    "babel-loader": "^8.2.4 || ^9.0.0 || ^10.0.0"
+  },
+  "swc": {
+    "@swc/core": "^1.3.0",
+    "swc-loader": "^0.2.0"
+  },
+  "esbuild": {
+    "esbuild": "^0.24.0",
+    "esbuild-loader": "^4.0.0"
+  }
+}