shakapacker 9.0.0.beta.0 → 9.0.0.beta.3

data/docs/rspack_migration_guide.md

@@ -0,0 +1,202 @@
+# Rspack Migration Guide for Shakapacker
+
+## Overview
+This guide documents the differences between webpack and Rspack configurations in Shakapacker, and provides migration guidance for users switching to Rspack.
+
+## Key Differences from Webpack
+
+### 1. Built-in Loaders
+Rspack provides built-in loaders for better performance:
+
+**JavaScript/TypeScript:**
+- Use `builtin:swc-loader` instead of `babel-loader` or `ts-loader`
+- 20x faster than Babel on single thread, 70x on multiple cores
+- Configuration example:
+```javascript
+{
+  test: /\.(js|jsx|ts|tsx)$/,
+  loader: 'builtin:swc-loader',
+  options: {
+    jsc: {
+      parser: {
+        syntax: 'typescript', // or 'ecmascript'
+        tsx: true, // for TSX files
+        jsx: true  // for JSX files
+      },
+      transform: {
+        react: {
+          runtime: 'automatic'
+        }
+      }
+    }
+  }
+}
+```
+
+### 2. Plugin Replacements
+
+#### Built-in Rspack Alternatives
+| Webpack Plugin | Rspack Alternative | Status |
+|---------------|-------------------|---------|
+| `copy-webpack-plugin` | `rspack.CopyRspackPlugin` | ✅ Built-in |
+| `mini-css-extract-plugin` | `rspack.CssExtractRspackPlugin` | ✅ Built-in |
+| `terser-webpack-plugin` | `rspack.SwcJsMinimizerRspackPlugin` | ✅ Built-in |
+| `css-minimizer-webpack-plugin` | `rspack.LightningCssMinimizerRspackPlugin` | ✅ Built-in |
+
+#### Community Alternatives
+| Webpack Plugin | Rspack Alternative | Package |
+|---------------|-------------------|----------|
+| `fork-ts-checker-webpack-plugin` | `ts-checker-rspack-plugin` | `npm i -D ts-checker-rspack-plugin` |
+| `@pmmmwh/react-refresh-webpack-plugin` | `@rspack/plugin-react-refresh` | `npm i -D @rspack/plugin-react-refresh` |
+| `eslint-webpack-plugin` | `eslint-rspack-plugin` | `npm i -D eslint-rspack-plugin` |
+
+#### Incompatible Plugins
+The following webpack plugins are NOT compatible with Rspack:
+- `webpack.optimize.LimitChunkCountPlugin` - Use `optimization.splitChunks` configuration instead
+- `webpack-manifest-plugin` - Use `rspack-manifest-plugin` instead
+- Git revision plugins - Use alternative approaches
+
+### 3. Asset Module Types
+Replace file loaders with asset modules:
+- `file-loader` → `type: 'asset/resource'`
+- `url-loader` → `type: 'asset/inline'`
+- `raw-loader` → `type: 'asset/source'`
+
+### 4. Configuration Differences
+
+#### TypeScript Configuration
+**Required:** Add `isolatedModules: true` to your `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "isolatedModules": true
+  }
+}
+```
+
+#### React Fast Refresh
+```javascript
+// Development configuration
+const ReactRefreshPlugin = require('@rspack/plugin-react-refresh');
+
+module.exports = {
+  plugins: [
+    new ReactRefreshPlugin(),
+    new rspack.HotModuleReplacementPlugin()
+  ]
+};
+```
+
+### 5. Optimization Differences
+
+#### Code Splitting
+Rspack's `splitChunks` configuration is similar to webpack but with some differences:
+```javascript
+optimization: {
+  splitChunks: {
+    chunks: 'all',
+    cacheGroups: {
+      vendor: {
+        test: /[\\/]node_modules[\\/]/,
+        priority: -10,
+        reuseExistingChunk: true
+      }
+    }
+  }
+}
+```
+
+#### Minimization
+```javascript
+optimization: {
+  minimize: true,
+  minimizer: [
+    new rspack.SwcJsMinimizerRspackPlugin(),
+    new rspack.LightningCssMinimizerRspackPlugin()
+  ]
+}
+```
+
+### 6. Development Server
+Rspack uses its own dev server with some configuration differences:
+```javascript
+devServer: {
+  // Rspack-specific: Force writing assets to disk
+  devMiddleware: {
+    writeToDisk: true
+  }
+}
+```
+
+## Migration Checklist
+
+### Step 1: Update Dependencies
+```bash
+# Remove webpack dependencies
+npm uninstall webpack webpack-cli webpack-dev-server
+
+# Install Rspack
+npm install --save-dev @rspack/core @rspack/cli
+```
+
+### Step 2: Update Configuration Files
+1. Create `config/rspack/rspack.config.js` based on your webpack config
+2. Update `config/shakapacker.yml`:
+```yaml
+assets_bundler: 'rspack'
+```
+
+### Step 3: Replace Loaders
+- Replace `babel-loader` with `builtin:swc-loader`
+- Remove `file-loader`, `url-loader`, `raw-loader` - use asset modules
+- Update CSS loaders to use Rspack's built-in support
+
+### Step 4: Update Plugins
+- Replace plugins with Rspack alternatives (see table above)
+- Remove incompatible plugins
+- Add Rspack-specific plugins as needed
+
+### Step 5: TypeScript Setup
+1. Add `isolatedModules: true` to `tsconfig.json`
+2. Optional: Add `ts-checker-rspack-plugin` for type checking
+
+### Step 6: Test Your Build
+```bash
+# Development build
+bin/shakapacker
+
+# Production build
+bin/shakapacker --mode production
+```
+
+## Common Issues and Solutions
+
+### Issue: LimitChunkCountPlugin Error
+**Error:** `Cannot read properties of undefined (reading 'tap')`
+**Solution:** Remove `webpack.optimize.LimitChunkCountPlugin` and use `splitChunks` configuration instead.
+
+### Issue: Missing Loaders
+**Error:** Module parse errors
+**Solution:** Check console logs for skipped loaders and install missing dependencies.
+
+### Issue: CSS Extraction
+**Error:** CSS not being extracted properly
+**Solution:** Use `rspack.CssExtractRspackPlugin` instead of `mini-css-extract-plugin`.
+
+### Issue: TypeScript Errors
+**Error:** TypeScript compilation errors
+**Solution:** Ensure `isolatedModules: true` is set in `tsconfig.json`.
+
+## Performance Tips
+
+1. **Use Built-in Loaders:** Always prefer Rspack's built-in loaders for better performance
+2. **Minimize Plugins:** Use only necessary plugins as each adds overhead
+3. **Enable Caching:** Rspack has built-in persistent caching
+4. **Use SWC:** The built-in SWC loader is significantly faster than Babel
+
+## Resources
+
+- [Rspack Documentation](https://rspack.rs)
+- [Rspack Examples](https://github.com/rspack-contrib/rspack-examples)
+- [Awesome Rspack](https://github.com/rspack-contrib/awesome-rspack)
+- [Migration Guide](https://rspack.rs/guide/migration/webpack)

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,7 +24,7 @@ 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`
+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
@@ -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

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.

data/docs/v9_upgrade.md

@@ -0,0 +1,185 @@
+# Shakapacker v9 Upgrade Guide
+
+This guide outlines breaking changes and migration steps for upgrading from Shakapacker v8 to v9.
+
+## Breaking Changes
+
+### 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.
+
+**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. 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)
+```
+
+## 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:
+
+```css
+/* styles.module.css */
+.my-button { }
+.primary-color { }
+```
+
+```js
+// v9 imports
+import { myButton, primaryColor } from './styles.module.css';
+```
+
+### 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.
+
+## 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,24 +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 "pathname"
 require "shakapacker"
+require "shakapacker/runner"
 
-APP_ROOT = File.expand_path("..", __dir__)
-Dir.chdir(APP_ROOT) do
-  config = Shakapacker::Configuration.new(
-    root_path: Pathname.new(APP_ROOT),
-    config_path: Pathname.new(File.join(APP_ROOT, "config/shakapacker.yml")),
-    env: ENV["RAILS_ENV"] || ENV["NODE_ENV"] || "development"
-  )
-
-  if config.rspack?
-    require "shakapacker/rspack_runner"
-    Shakapacker::RspackRunner.run(ARGV)
-  else
-    require "shakapacker/webpack_runner"
-    Shakapacker::WebpackRunner.run(ARGV)
-  end
-end
+Shakapacker::Runner.run(ARGV)

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,11 +40,12 @@ 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 are 'babel' (default), 'swc' or 'esbuild'
+  javascript_transpiler: 'babel'
 
-  # Select bundler to use, available options are 'webpack' (default) or 'rspack'
-  bundler: 'webpack'
+  # 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/shakapacker/configuration.rb

@@ -68,6 +68,13 @@ class Shakapacker::Configuration
     root_path.join(fetch(:public_root_path))
   end
 
+  def private_output_path
+    private_path = fetch(:private_output_path)
+    return nil unless private_path
+    validate_output_paths!
+    root_path.join(private_path)
+  end
+
   def public_output_path
     public_path.join(fetch(:public_output_path))
   end
@@ -88,18 +95,51 @@ class Shakapacker::Configuration
     fetch(:compiler_strategy)
   end
 
+  def assets_bundler
+    # Show deprecation warning if using old 'bundler' key
+    if data.has_key?(:bundler) && !data.has_key?(:assets_bundler)
+      $stderr.puts "⚠️  DEPRECATION WARNING: The 'bundler' configuration option is deprecated. Please use 'assets_bundler' instead to avoid confusion with Ruby's Bundler gem manager."
+    end
+    ENV["SHAKAPACKER_ASSETS_BUNDLER"] || fetch(:assets_bundler) || fetch(:bundler) || "webpack"
+  end
+
+  # Deprecated: Use assets_bundler instead
   def bundler
-    fetch(:bundler) || "webpack"
+    assets_bundler
   end
 
   def rspack?
-    bundler == "rspack"
+    assets_bundler == "rspack"
   end
 
   def webpack?
-    bundler == "webpack"
+    assets_bundler == "webpack"
   end
 
+  def javascript_transpiler
+    # Show deprecation warning if using old 'webpack_loader' key
+    if data.has_key?(:webpack_loader) && !data.has_key?(:javascript_transpiler)
+      $stderr.puts "⚠️  DEPRECATION WARNING: The 'webpack_loader' configuration option is deprecated. Please use 'javascript_transpiler' instead as it better reflects its purpose of configuring JavaScript transpilation regardless of the bundler used."
+    end
+
+    # Use explicit config if set, otherwise default based on bundler
+    fetch(:javascript_transpiler) || fetch(:webpack_loader) || default_javascript_transpiler
+  end
+
+  # Deprecated: Use javascript_transpiler instead
+  def webpack_loader
+    javascript_transpiler
+  end
+
+  private
+
+    def default_javascript_transpiler
+      # RSpack has built-in SWC support, use it by default
+      rspack? ? "swc" : "babel"
+    end
+
+  public
+
   def fetch(key)
     data.fetch(key, defaults[key])
   end
@@ -116,6 +156,38 @@ class Shakapacker::Configuration
   end
 
   private
+    def validate_output_paths!
+      # Skip validation if already validated to avoid redundant checks
+      return if @validated_output_paths
+      @validated_output_paths = true
+
+      # Only validate when both paths are configured
+      return unless fetch(:private_output_path) && fetch(:public_output_path)
+
+      private_path_str, public_path_str = resolve_paths_for_comparison
+
+      if private_path_str == public_path_str
+        raise "Shakapacker configuration error: private_output_path and public_output_path must be different. " \
+              "Both paths resolve to '#{private_path_str}'. " \
+              "The private_output_path is for server-side bundles (e.g., SSR) that should not be served publicly."
+      end
+    end
+
+    def resolve_paths_for_comparison
+      private_full_path = root_path.join(fetch(:private_output_path))
+      public_full_path = root_path.join(fetch(:public_root_path), fetch(:public_output_path))
+
+      # Create directories if they don't exist (for testing)
+      private_full_path.mkpath unless private_full_path.exist?
+      public_full_path.mkpath unless public_full_path.exist?
+
+      # Use realpath to resolve symbolic links and relative paths
+      [private_full_path.realpath.to_s, public_full_path.realpath.to_s]
+    rescue Errno::ENOENT
+      # If paths don't exist yet, fall back to cleanpath for comparison
+      [private_full_path.cleanpath.to_s, public_full_path.cleanpath.to_s]
+    end
+
     def data
       @data ||= load
     end

data/lib/shakapacker/dev_server_runner.rb

@@ -7,6 +7,10 @@ require_relative "runner"
 
 module Shakapacker
   class DevServerRunner < Shakapacker::Runner
+    def self.run(argv)
+      new(argv).run
+    end
+
     def run
       load_config
       detect_unsupported_switches!
@@ -75,17 +79,16 @@ module Shakapacker
           env["NODE_OPTIONS"] = "#{env["NODE_OPTIONS"]} --inspect-brk --trace-warnings"
         end
 
-        # Add bundler-specific flags and config
-        bundler = get_bundler_type
-        if bundler == "webpack"
-          cmd += ["--config", @webpack_config]
+        # Add config file
+        cmd += ["--config", @webpack_config]
+
+        # Add assets bundler-specific flags
+        if webpack?
           cmd += ["--progress", "--color"] if @pretty
           # Default behavior of webpack-dev-server is @hot = true
           cmd += ["--hot", "only"] if @hot == "only"
           cmd += ["--no-hot"] if !@hot
-        elsif bundler == "rspack"
-          # Only add config for rspack if it's not a rspack-specific command
-          cmd += ["--config", @webpack_config]
+        elsif rspack?
           # Rspack supports --hot but not --no-hot or --progress/--color
           cmd += ["--hot"] if @hot && @hot != false
         end
@@ -98,9 +101,16 @@ module Shakapacker
       end
 
       def build_cmd
-        bundler = get_bundler_type
-        command = bundler == "rspack" ? "rspack" : "webpack"
+        command = @config.rspack? ? "rspack" : "webpack"
         package_json.manager.native_exec_command(command, ["serve"])
       end
+
+      def webpack?
+        @config.webpack?
+      end
+
+      def rspack?
+        @config.rspack?
+      end
   end
 end