shakapacker 8.0.2 → 9.2.0

data/docs/typescript-migration.md

@@ -0,0 +1,379 @@
+# TypeScript Migration Guide for Shakapacker
+
+This guide helps you adopt TypeScript types in your Shakapacker configuration files for better type safety and IDE support.
+
+## Table of Contents
+- [Benefits](#benefits)
+- [Quick Start](#quick-start)
+- [Migration Steps](#migration-steps)
+- [Common Patterns](#common-patterns)
+- [Troubleshooting](#troubleshooting)
+
+## Benefits
+
+Using TypeScript with Shakapacker provides:
+- **Type Safety**: Catch configuration errors at compile time
+- **IDE Support**: Get autocompletion and inline documentation
+- **Better Refactoring**: Safely rename and restructure configurations
+- **Self-documenting**: Types serve as inline documentation
+
+## Quick Start
+
+### 1. Install TypeScript Dependencies
+
+```bash
+yarn add --dev typescript @types/node @types/webpack
+# or
+npm install --save-dev typescript @types/node @types/webpack
+```
+
+### 2. Create a tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true
+  },
+  "include": ["config/webpack/**/*"],
+  "exclude": ["node_modules"]
+}
+```
+
+### 3. Convert Your Webpack Config to TypeScript
+
+Rename `config/webpack/webpack.config.js` to `config/webpack/webpack.config.ts`:
+
+```typescript
+// config/webpack/webpack.config.ts
+import { generateWebpackConfig, merge } from 'shakapacker'
+import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+import type { Configuration } from 'webpack'
+
+const customConfig: Configuration = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx']
+  }
+}
+
+const config: Configuration = generateWebpackConfig(customConfig)
+
+export default config
+```
+
+## Migration Steps
+
+### Step 1: Import Types
+
+Start by importing the types you need:
+
+```typescript
+import type {
+  Config,
+  WebpackConfigWithDevServer,
+  RspackConfigWithDevServer,
+  CompressionPluginOptions
+} from 'shakapacker/types'
+```
+
+### Step 2: Type Your Configuration Objects
+
+Add type annotations to your configuration objects:
+
+```typescript
+// Before (JavaScript)
+const customConfig = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx']
+  }
+}
+
+// After (TypeScript)
+import type { Configuration } from 'webpack'
+
+const customConfig: Configuration = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx']
+  }
+}
+```
+
+### Step 3: Type Your Custom Functions
+
+If you have custom configuration functions, add type annotations:
+
+```typescript
+// Before (JavaScript)
+function modifyConfig(config) {
+  config.plugins.push(new MyPlugin())
+  return config
+}
+
+// After (TypeScript)
+import type { Configuration } from 'webpack'
+import type { WebpackPluginInstance } from 'shakapacker/types'
+
+function modifyConfig(config: Configuration): Configuration {
+  const plugins = config.plugins as WebpackPluginInstance[]
+  plugins.push(new MyPlugin())
+  return config
+}
+```
+
+### Step 4: Handle Environment-Specific Configurations
+
+```typescript
+// config/webpack/development.ts
+import { generateWebpackConfig } from 'shakapacker'
+import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+
+const developmentConfig: WebpackConfigWithDevServer = generateWebpackConfig({
+  devtool: 'eval-cheap-module-source-map',
+  devServer: {
+    hot: true,
+    port: 3035
+  }
+})
+
+export default developmentConfig
+```
+
+## Common Patterns
+
+### Pattern 1: Custom Loaders
+
+```typescript
+import type { RuleSetRule } from 'webpack'
+
+const customLoader: RuleSetRule = {
+  test: /\.svg$/,
+  use: ['@svgr/webpack']
+}
+
+const config: Configuration = generateWebpackConfig({
+  module: {
+    rules: [customLoader]
+  }
+})
+```
+
+### Pattern 2: Plugin Configuration
+
+```typescript
+import CompressionPlugin from 'compression-webpack-plugin'
+import type { CompressionPluginOptions } from 'shakapacker/types'
+
+const compressionOptions: CompressionPluginOptions = {
+  filename: '[path][base].gz',
+  algorithm: 'gzip',
+  test: /\.(js|css|html|json|ico|svg|eot|otf|ttf)$/
+}
+
+const config: Configuration = generateWebpackConfig({
+  plugins: [new CompressionPlugin(compressionOptions)]
+})
+```
+
+### Pattern 3: Conditional Configuration
+
+```typescript
+import type { Configuration } from 'webpack'
+import { env } from 'shakapacker'
+
+const config: Configuration = generateWebpackConfig()
+
+if (env.isProduction) {
+  // TypeScript knows config.optimization exists
+  config.optimization = {
+    ...config.optimization,
+    minimize: true,
+    sideEffects: false
+  }
+}
+
+export default config
+```
+
+### Pattern 4: Rspack Configuration
+
+```typescript
+// config/rspack/rspack.config.ts
+import type { RspackConfigWithDevServer } from 'shakapacker/types'
+import { generateWebpackConfig } from 'shakapacker'
+
+const rspackConfig: RspackConfigWithDevServer = generateWebpackConfig({
+  mode: 'development',
+  devServer: {
+    hot: true,
+    port: 3036
+  }
+})
+
+export default rspackConfig
+```
+
+## Type-checking Your Configuration
+
+Add a script to your package.json to type-check your configuration:
+
+```json
+{
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "webpack:type-check": "tsc --noEmit config/webpack/*.ts"
+  }
+}
+```
+
+Run type checking:
+
+```bash
+yarn type-check
+# or
+npm run type-check
+```
+
+## Available Types Reference
+
+### Core Types
+- `Config` - Shakapacker configuration from shakapacker.yml
+- `Env` - Environment variables and helpers
+- `DevServerConfig` - Development server configuration
+
+### Webpack/Rspack Types
+- `WebpackConfigWithDevServer` - Webpack configuration with dev server
+- `RspackConfigWithDevServer` - Rspack configuration with dev server
+- `WebpackPluginInstance` - Webpack plugin instance type
+- `RspackPluginInstance` - Rspack plugin instance type
+- `RspackPlugin` - **⚠️ Deprecated:** Use `RspackPluginInstance` instead
+
+### Helper Types
+- `CompressionPluginOptions` - Compression plugin configuration
+- `ReactRefreshWebpackPlugin` - React refresh for Webpack
+- `ReactRefreshRspackPlugin` - React refresh for Rspack
+
+## Troubleshooting
+
+### Issue: "Cannot find module 'shakapacker/types'"
+
+**Solution**: Make sure you're using Shakapacker v9.0.0 or later:
+
+```bash
+yarn upgrade shakapacker
+```
+
+### Issue: Type errors with plugins
+
+**Solution**: Cast plugin arrays when needed:
+
+```typescript
+const plugins = (config.plugins || []) as WebpackPluginInstance[]
+plugins.push(new MyPlugin())
+```
+
+### Issue: Missing types for custom loaders
+
+**Solution**: Install type definitions or declare them:
+
+```typescript
+// If types aren't available, declare them
+declare module 'my-custom-loader' {
+  const loader: any
+  export default loader
+}
+```
+
+### Issue: Conflicting types between webpack versions
+
+**Solution**: Ensure your webpack types match your webpack version:
+
+```bash
+yarn add --dev @types/webpack@^5
+```
+
+## Gradual Migration
+
+You don't need to convert everything at once. Start with:
+
+1. Convert your main webpack.config.js to TypeScript
+2. Add types to the most complex configurations
+3. Gradually type other configuration files
+4. Add type checking to your CI pipeline
+
+## Example: Full Configuration
+
+Here's a complete example of a typed webpack configuration:
+
+```typescript
+// config/webpack/webpack.config.ts
+import { generateWebpackConfig, merge, config as shakapackerConfig } from 'shakapacker'
+import type { Configuration } from 'webpack'
+import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+import CompressionPlugin from 'compression-webpack-plugin'
+import { resolve } from 'path'
+
+// Type-safe custom configuration
+const customConfig: Configuration = {
+  resolve: {
+    extensions: ['.css', '.ts', '.tsx'],
+    alias: {
+      '@': resolve(__dirname, '../../app/javascript'),
+      'components': resolve(__dirname, '../../app/javascript/components'),
+      'utils': resolve(__dirname, '../../app/javascript/utils')
+    }
+  },
+  module: {
+    rules: [
+      {
+        test: /\.svg$/,
+        use: ['@svgr/webpack'],
+        issuer: /\.(tsx?|jsx?)$/
+      }
+    ]
+  }
+}
+
+// Generate the final configuration
+const webpackConfig: Configuration = generateWebpackConfig(customConfig)
+
+// Type-safe modifications based on environment
+if (shakapackerConfig.env === 'production') {
+  const plugins = (webpackConfig.plugins || []) as WebpackPluginInstance[]
+
+  plugins.push(
+    new CompressionPlugin({
+      filename: '[path][base].br',
+      algorithm: 'brotliCompress',
+      test: /\.(js|css|html|json|ico|svg|eot|otf|ttf)$/
+    })
+  )
+}
+
+export default webpackConfig
+```
+
+## Next Steps
+
+After migrating to TypeScript:
+
+1. **Enable strict checks**: Gradually enable stricter TypeScript options
+2. **Add custom types**: Create type definitions for your application-specific configurations
+3. **Share types**: Export reusable configuration types for your team
+4. **Document with types**: Use JSDoc comments with your types for better documentation
+
+## Resources
+
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
+- [Webpack TypeScript Configuration](https://webpack.js.org/configuration/configuration-languages/#typescript)
+- [Shakapacker Types Documentation](./types/README.md)
+- [Migration Examples](https://github.com/shakacode/shakapacker/tree/main/examples/typescript-config)

data/docs/typescript.md

@@ -0,0 +1,99 @@
+# TypeScript Support
+
+Shakapacker v9 includes TypeScript support, providing type safety and better IDE experience for your webpack configurations.
+
+## Quick Start
+
+### Using TypeScript Config
+
+```typescript
+// webpack.config.ts
+import { generateWebpackConfig } from 'shakapacker'
+import type { Configuration } from 'webpack'
+
+const config: Configuration = generateWebpackConfig({
+  // Your config with full type safety
+})
+
+export default config
+```
+
+### Using JSDoc (JavaScript)
+
+```javascript
+// webpack.config.js
+const { generateWebpackConfig } = require('shakapacker')
+
+/** @type {import('webpack').Configuration} */
+const config = {
+  // Still get autocomplete in JS files!
+}
+
+module.exports = generateWebpackConfig(config)
+```
+
+## Benefits
+
+- **Compile-time error detection** - Catch config errors before runtime
+- **IDE autocomplete** - Full IntelliSense for all options
+- **Type safety** - Prevents 85-100% of common configuration errors
+- **No breaking changes** - Fully backward compatible
+
+## Migration
+
+1. **No migration required** - Existing JavaScript configs continue to work
+2. **Optional TypeScript** - Use it only if you want the benefits
+3. **Gradual adoption** - Start with JSDoc comments, move to TypeScript later
+
+## IDE Setup
+
+### VS Code
+- Install TypeScript extension (built-in)
+- Set `"typescript.tsdk": "node_modules/typescript/lib"` in settings
+
+### WebStorm/IntelliJ
+- Enable TypeScript service in Settings → Languages & Frameworks → TypeScript
+
+## Common Patterns
+
+### Environment-Specific Config
+
+```typescript
+import { generateWebpackConfig, env } from 'shakapacker'
+
+const config = generateWebpackConfig({
+  optimization: {
+    minimize: env.isProduction
+  }
+})
+```
+
+### Rspack Config
+
+```typescript
+import { generateRspackConfig } from 'shakapacker/rspack'
+import type { RspackOptions } from '@rspack/core'
+
+const config: RspackOptions = {
+  // Rspack-specific config
+}
+
+export default generateRspackConfig(config)
+```
+
+## Troubleshooting
+
+**Cannot find module 'shakapacker'**
+```typescript
+/// <reference types="shakapacker" />
+```
+
+**Type errors with custom loaders**
+```typescript
+use: [require.resolve('custom-loader') as any]
+```
+
+## Further Reading
+
+- [Webpack TypeScript Documentation](https://webpack.js.org/configuration/configuration-languages/#typescript)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

data/docs/using_esbuild_loader.md

@@ -27,7 +27,7 @@ To use esbuild as your transpiler today. You need to do two things:
 npm install esbuild esbuild-loader
 ```
 
-2. Add or change `webpack_loader` value in your default `shakapacker.yml` config to `esbuild`
+2. Add or change `javascript_transpiler` value in your default `shakapacker.yml` config to `esbuild`
 The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
 
 ```yml
@@ -46,8 +46,8 @@ 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: 'esbuild'
+  # Select JavaScript transpiler to use, available options are 'babel' (default), 'swc' or 'esbuild'
+  javascript_transpiler: 'esbuild'
 ```
 
 ### (Optional) Replace minification with esbuild

data/docs/using_swc_loader.md

@@ -12,6 +12,8 @@ It supports all ECMAScript features and it's designed to be a drop-in replacemen
 
 For comparison between SWC and Babel, see the docs at https://swc.rs/docs/migrating-from-babel.
 
+> **Note:** SWC is also natively built into RSpack bundler, providing even faster compilation speeds. When using RSpack (`assets_bundler: 'rspack'`), SWC is used automatically regardless of the `javascript_transpiler` setting.
+
 ## Switching your Shakapacker project to SWC
 
 In order to use SWC as your compiler today. You need to do two things:
@@ -22,8 +24,8 @@ In order to use SWC as your compiler today. You need to do two things:
 npm install @swc/core swc-loader
 ```
 
-2. Add or change `webpack_loader` value in your default `shakapacker.yml` config to `swc`
-The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
+2. Add or change `javascript_transpiler` value in your default `shakapacker.yml` config to `swc`
+   The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
 
 ```yml
 default: &default
@@ -41,8 +43,8 @@ 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) or 'swc'
-  webpack_loader: 'swc'
+  # Select JavaScript transpiler to use, available options are 'babel' (default) or 'swc'
+  javascript_transpiler: "swc"
 ```
 
 ## Usage
@@ -71,7 +73,6 @@ See some examples below of potential `config/swc.config.js`.
 
 ### Example: Enabling top level await and decorators
 
-
 ```js
 const customConfig = {
   options: {
@@ -90,7 +91,7 @@ module.exports = customConfig
 ### Example: Matching existing `@babel/present-env` config
 
 ```js
-const { env } = require('shakapacker')
+const { env } = require("shakapacker")
 
 const customConfig = {
   options: {
@@ -112,9 +113,8 @@ module.exports = customConfig
 
 :warning: Remember that you still need to add [@pmmmwh/react-refresh-webpack-plugin](https://github.com/pmmmwh/react-refresh-webpack-plugin) to your webpack config. The setting below just replaces equivalent `react-refresh/babel` Babel plugin.
 
-
 ```js
-const { env } = require('shakapacker')
+const { env } = require("shakapacker")
 
 const customConfig = {
   options: {
@@ -134,11 +134,10 @@ module.exports = customConfig
 ### Example: Adding browserslist config
 
 ```js
-
 const customConfig = {
   options: {
     env: {
-      targets: '> 0.25%, not dead'
+      targets: "> 0.25%, not dead"
     }
   }
 }
@@ -146,6 +145,109 @@ const customConfig = {
 module.exports = customConfig
 ```
 
+## Using SWC with Stimulus
+
+⚠️ **Important:** If you're using [Stimulus](https://stimulus.hotwired.dev/), you need to configure SWC to preserve class names.
+
+### Required Configuration
+
+SWC mangles (minifies) class names by default for optimization. Since Stimulus relies on class names to discover and instantiate controllers, you must preserve class names in your `config/swc.config.js`:
+
+```js
+// config/swc.config.js
+const { env } = require("shakapacker")
+
+module.exports = {
+  options: {
+    jsc: {
+      // CRITICAL for Stimulus: Prevents SWC from mangling class names
+      keepClassNames: true,
+      transform: {
+        react: {
+          runtime: "automatic",
+          refresh: env.isDevelopment && env.runningWebpackDevServer
+        }
+      }
+    }
+  }
+}
+```
+
+**Note:** Starting with Shakapacker v9.1.0, the default `swc.config.js` created by `rake shakapacker:migrate_to_swc` includes `keepClassNames: true` automatically.
+
+### Why This Matters
+
+Without `keepClassNames: true`, your Stimulus controllers will:
+
+- Load without errors in the browser console
+- Fail silently at runtime
+- Not respond to events
+- Not update the DOM as expected
+
+This makes debugging very difficult since there are no visible JavaScript errors.
+
+### Symptoms of Missing Configuration
+
+If your Stimulus controllers aren't working after migrating to SWC, you'll typically see test failures like:
+
+```
+Failure/Error: expect(page).to have_text("Author: can't be blank")
+  expected to be truthy, got false
+
+Failure/Error: expect(page).to have_css("h2", text: comment.author)
+  expected to be truthy, got false
+```
+
+Your controllers appear to load but don't function correctly:
+
+- Form submissions don't work
+- Validation error messages don't appear
+- Dynamic content doesn't get added to the page
+- No JavaScript errors appear in the console
+
+### Common Configuration Error
+
+❌ **Error:** `` `env` and `jsc.target` cannot be used together``
+
+If you see this error:
+
+```
+ERROR in ./client/app/packs/stimulus-bundle.js
+Module build failed (from ./node_modules/swc-loader/src/index.js):
+Error:
+
+Caused by:
+    `env` and `jsc.target` cannot be used together
+```
+
+**Solution:** Do NOT add `jsc.target` to your configuration. Shakapacker already sets `env` for browser targeting. Use `env` OR `jsc.target`, never both.
+
+❌ **Incorrect:**
+
+```js
+jsc: {
+  target: 'es2015',  // Don't add this!
+  keepClassNames: true,
+}
+```
+
+✅ **Correct:**
+
+```js
+jsc: {
+  keepClassNames: true,  // No target specified
+}
+```
+
+### Troubleshooting Checklist
+
+If your Stimulus controllers aren't working after migrating to SWC:
+
+1. ✅ Verify `keepClassNames: true` is set in `config/swc.config.js`
+2. ✅ Ensure your controllers have explicit class names (not anonymous classes)
+3. ✅ Test with `console.log()` in your controller's `connect()` method to verify it's being instantiated
+4. ✅ Check that you haven't added `jsc.target` (which conflicts with Shakapacker's `env` setting)
+5. ✅ Rebuild your assets: `bin/shakapacker clobber && bin/shakapacker compile`
 
 ## Known limitations
 

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.