shakapacker 9.0.0.beta.2 → 9.0.0.beta.4

data/docs/v9_upgrade.md

@@ -0,0 +1,228 @@
+# 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. 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)
+```
+
+## 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/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,10 @@ default: &default
   # Reload manifest.json on all requests so we reload latest compiled packs
   cache_manifest: false
 
-  # Select JavaScript transpiler to use, available options are 'babel' (default), 'swc' or 'esbuild'
-  javascript_transpiler: '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'

data/lib/install/package.json

@@ -26,5 +26,13 @@
     "@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"
   }
 }

data/lib/install/template.rb

@@ -2,25 +2,56 @@ require "shakapacker/utils/misc"
 require "shakapacker/utils/manager"
 require "shakapacker/utils/version_syntax_converter"
 require "package_json"
+require "yaml"
+require "json"
 
 # Install Shakapacker
 
 force_option = ENV["FORCE"] ? { force: true } : {}
 
-copy_file "#{__dir__}/config/shakapacker.yml", "config/shakapacker.yml", force_option
+# Initialize variables for use throughout the template
+# Using instance variable to avoid method definition issues in Rails templates
+@package_json ||= PackageJson.new
+install_dir = File.expand_path(File.dirname(__FILE__))
+
+# Installation strategy:
+# - USE_BABEL_PACKAGES installs both babel AND swc for compatibility
+# - Otherwise install only the specified transpiler
+if ENV["USE_BABEL_PACKAGES"] == "true" || ENV["USE_BABEL_PACKAGES"] == "1"
+  @transpiler_to_install = "babel"
+  say "📦 Installing Babel packages (USE_BABEL_PACKAGES is set)", :yellow
+  say "✨ Also installing SWC packages for default config compatibility", :green
+elsif ENV["JAVASCRIPT_TRANSPILER"]
+  @transpiler_to_install = ENV["JAVASCRIPT_TRANSPILER"]
+  say "📦 Installing #{@transpiler_to_install} packages", :blue
+else
+  # Default to swc (matches the default in shakapacker.yml)
+  @transpiler_to_install = "swc"
+  say "✨ Installing SWC packages (20x faster than Babel)", :green
+end
+
+# Copy config file
+copy_file "#{install_dir}/config/shakapacker.yml", "config/shakapacker.yml", force_option
+
+# Update config if USE_BABEL_PACKAGES is set to ensure babel is used at runtime
+if @transpiler_to_install == "babel" && !ENV["JAVASCRIPT_TRANSPILER"]
+  # When USE_BABEL_PACKAGES is set, update the config to use babel
+  gsub_file "config/shakapacker.yml", "javascript_transpiler: 'swc'", "javascript_transpiler: 'babel'"
+  say "   📝 Updated config/shakapacker.yml to use Babel transpiler", :green
+end
 
 say "Copying webpack core config"
-directory "#{__dir__}/config/webpack", "config/webpack", force_option
+directory "#{install_dir}/config/webpack", "config/webpack", force_option
 
 if Dir.exist?(Shakapacker.config.source_path)
   say "The packs app source directory already exists"
 else
   say "Creating packs app source directory"
   empty_directory "app/javascript/packs"
-  copy_file "#{__dir__}/application.js", "app/javascript/packs/application.js"
+  copy_file "#{install_dir}/application.js", "app/javascript/packs/application.js"
 end
 
-apply "#{__dir__}/binstubs.rb"
+apply "#{install_dir}/binstubs.rb"
 
 git_ignore_path = Rails.root.join(".gitignore")
 if File.exist?(git_ignore_path)
@@ -43,17 +74,8 @@ else
   say %(        Add <%= javascript_pack_tag "application" %> within the <head> tag in your custom layout.)
 end
 
-def package_json
-  @package_json ||= PackageJson.new
-end
-
 # setup the package manager with default values
-package_json.merge! do |pj|
-  babel = pj.fetch("babel", {})
-
-  babel["presets"] ||= []
-  babel["presets"].push("./node_modules/shakapacker/package/babel/preset.js")
-
+@package_json.merge! do |pj|
   package_manager = pj.fetch("packageManager") do
     "#{Shakapacker::Utils::Manager.guess_binary}@#{Shakapacker::Utils::Manager.guess_version}"
   end
@@ -62,7 +84,6 @@ package_json.merge! do |pj|
     "name" => "app",
     "private" => true,
     "version" => "0.1.0",
-    "babel" => babel,
     "browserslist" => [
       "defaults"
     ],
@@ -74,7 +95,7 @@ Shakapacker::Utils::Manager.error_unless_package_manager_is_obvious!
 
 # Ensure there is `system!("bin/yarn")` command in `./bin/setup` file
 if (setup_path = Rails.root.join("bin/setup")).exist?
-  native_install_command = package_json.manager.native_install_command.join(" ")
+  native_install_command = @package_json.manager.native_install_command.join(" ")
 
   say "Run #{native_install_command} during bin/setup"
 
@@ -103,42 +124,56 @@ if (setup_path = Rails.root.join("bin/setup")).exist?
   end
 end
 
-def add_dependencies(dependencies, type)
-  package_json.manager.add!(dependencies, type: type)
-rescue PackageJson::Error
-  say "Shakapacker installation failed 😭 See above for details.", :red
-  exit 1
-end
-
-def fetch_peer_dependencies
-  PackageJson.read("#{__dir__}").fetch(ENV["SHAKAPACKER_BUNDLER"] || "webpack")
-end
-
-def fetch_common_dependencies
-  ENV["SKIP_COMMON_LOADERS"] ? {} : PackageJson.read("#{__dir__}").fetch("common")
-end
-
-def fetch_babel_dependencies
-  ENV["USE_BABEL_PACKAGES"] ? PackageJson.read("#{__dir__}").fetch("babel") : {}
-end
-
 Dir.chdir(Rails.root) do
   npm_version = Shakapacker::Utils::VersionSyntaxConverter.new.rubygem_to_npm(Shakapacker::VERSION)
   say "Installing shakapacker@#{npm_version}"
-  add_dependencies(["shakapacker@#{npm_version}"], :production)
-
-  package_json.merge! do |pj|
-    {
-      "dependencies" => pj["dependencies"].merge({
-        # TODO: workaround for test suite - long-run need to actually account for diff pkg manager behaviour
-        "shakapacker" => pj["dependencies"]["shakapacker"].delete_prefix("^")
-      })
-    }
+  begin
+    @package_json.manager.add!(["shakapacker@#{npm_version}"], type: :production)
+  rescue PackageJson::Error
+    say "Shakapacker installation failed 😭 See above for details.", :red
+    exit 1
   end
 
-  peers = fetch_peer_dependencies
-  peers = peers.merge(fetch_common_dependencies)
-  peers = peers.merge(fetch_babel_dependencies)
+  @package_json.merge! do |pj|
+    if pj["dependencies"] && pj["dependencies"]["shakapacker"]
+      {
+        "dependencies" => pj["dependencies"].merge({
+          # TODO: workaround for test suite - long-run need to actually account for diff pkg manager behaviour
+          "shakapacker" => pj["dependencies"]["shakapacker"].delete_prefix("^")
+        })
+      }
+    else
+      pj
+    end
+  end
+
+  # Inline fetch_peer_dependencies and fetch_common_dependencies
+  peers = PackageJson.read(install_dir).fetch(ENV["SHAKAPACKER_BUNDLER"] || "webpack")
+  common_deps = ENV["SKIP_COMMON_LOADERS"] ? {} : PackageJson.read(install_dir).fetch("common")
+  peers = peers.merge(common_deps)
+
+  # Add transpiler-specific dependencies based on detected/configured transpiler
+  # Inline the logic here since methods can't be called before they're defined in Rails templates
+
+  # Install transpiler-specific dependencies
+  # When USE_BABEL_PACKAGES is set, install both babel AND swc
+  # This ensures backward compatibility while supporting the default config
+  if @transpiler_to_install == "babel"
+    # Install babel packages
+    babel_deps = PackageJson.read(install_dir).fetch("babel")
+    peers = peers.merge(babel_deps)
+
+    # Also install SWC since that's what the default config uses
+    # This ensures the runtime works regardless of config
+    swc_deps = PackageJson.read(install_dir).fetch("swc")
+    peers = peers.merge(swc_deps)
+  elsif @transpiler_to_install == "swc"
+    swc_deps = PackageJson.read(install_dir).fetch("swc")
+    peers = peers.merge(swc_deps)
+  elsif @transpiler_to_install == "esbuild"
+    esbuild_deps = PackageJson.read(install_dir).fetch("esbuild")
+    peers = peers.merge(esbuild_deps)
+  end
 
   dev_dependency_packages = ["webpack-dev-server"]
 
@@ -146,8 +181,15 @@ Dir.chdir(Rails.root) do
   dev_dependencies_to_add = []
 
   peers.each do |(package, version)|
-    major_version = version.split("||").last.match(/(\d+)/)[1]
-    entry = "#{package}@#{major_version}"
+    # Handle versions like "^1.3.0" or ">= 4 || 5"
+    if version.start_with?("^", "~") || version.match?(/^\d+\.\d+/)
+      # Already has proper version format, use as-is
+      entry = "#{package}@#{version}"
+    else
+      # Extract major version from complex version strings like ">= 4 || 5"
+      major_version = version.split("||").last.match(/(\d+)/)[1]
+      entry = "#{package}@#{major_version}"
+    end
 
     if dev_dependency_packages.include? package
       dev_dependencies_to_add << entry
@@ -157,8 +199,36 @@ Dir.chdir(Rails.root) do
   end
 
   say "Adding shakapacker peerDependencies"
-  add_dependencies(dependencies_to_add, :production)
+  begin
+    @package_json.manager.add!(dependencies_to_add, type: :production)
+  rescue PackageJson::Error
+    say "Shakapacker installation failed 😭 See above for details.", :red
+    exit 1
+  end
 
   say "Installing webpack-dev-server for live reloading as a development dependency"
-  add_dependencies(dev_dependencies_to_add, :dev)
+  begin
+    @package_json.manager.add!(dev_dependencies_to_add, type: :dev)
+  rescue PackageJson::Error
+    say "Shakapacker installation failed 😭 See above for details.", :red
+    exit 1
+  end
+
+  # Configure babel preset in package.json if babel is being used
+  if @transpiler_to_install == "babel"
+    @package_json.merge! do |pj|
+      babel = pj.fetch("babel", {})
+      babel["presets"] ||= []
+      unless babel["presets"].include?("./node_modules/shakapacker/package/babel/preset.js")
+        babel["presets"].push("./node_modules/shakapacker/package/babel/preset.js")
+      end
+      { "babel" => babel }
+    end
+  end
+end
+
+# Helper methods defined at the end (Rails template convention)
+
+def package_json
+  @package_json
 end

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
@@ -149,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/version.rb

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

data/package/config.js

@@ -59,8 +59,8 @@ if (process.env.SHAKAPACKER_ASSETS_BUNDLER) {
 }
 
 // Define clear defaults
-const DEFAULT_JAVASCRIPT_TRANSPILER =
-  config.assets_bundler === "rspack" ? "swc" : "babel"
+// SWC is now the default transpiler for both webpack and rspack
+const DEFAULT_JAVASCRIPT_TRANSPILER = "swc"
 
 // Backward compatibility: Add webpack_loader property that maps to javascript_transpiler
 // Show deprecation warning if webpack_loader is used

data/package/index.d.ts

@@ -9,6 +9,7 @@ declare module "shakapacker" {
     css_extract_ignore_order_warnings: boolean
     public_root_path: string
     public_output_path: string
+    private_output_path?: string
     cache_path: string
     webpack_compile_output: boolean
     shakapacker_precompile: boolean
@@ -23,6 +24,14 @@ declare module "shakapacker" {
     publicPath: string
     publicPathWithoutCDN: string
     manifestPath: string
+    manifest_path?: string
+    assets_bundler?: string
+    dev_server?: DevServerConfig
+    integrity?: {
+      enabled: boolean
+      cross_origin: string
+      hash_functions?: string[]
+    }
   }
 
   export interface Env {
@@ -60,6 +69,8 @@ declare module "shakapacker" {
     ipc?: boolean | string
     magic_html?: boolean
     live_reload?: boolean
+    inline_css?: boolean
+    env_prefix?: string
     open?:
       | boolean
       | string
@@ -136,4 +147,4 @@ declare module "shakapacker/package/babel/preset.js" {
   ) => TransformOptions & RequiredTransformOptions
 
   export = defaultConfigFunc
-}
+}

data/package/rules/rspack.js

@@ -12,6 +12,8 @@ debug("Adding JavaScript rule with builtin:swc-loader")
 rules.push({
   test: /\.(js|jsx|mjs)$/,
   exclude: /node_modules/,
+  // The 'type' field is required for Rspack to properly handle JavaScript modules
+  // when using builtin loaders. It ensures correct module parsing and transformation.
   type: "javascript/auto",
   use: [
     {
@@ -38,6 +40,8 @@ debug("Adding TypeScript rule with builtin:swc-loader")
 rules.push({
   test: /\.(ts|tsx)$/,
   exclude: /node_modules/,
+  // The 'type' field is required for Rspack to properly handle TypeScript modules
+  // when using builtin loaders. It ensures correct module parsing and transformation.
   type: "javascript/auto",
   use: [
     {

data/package/utils/getStyleRule.js

@@ -3,6 +3,7 @@ const { canProcess, moduleExists } = require("./helpers")
 const { requireOrError } = require("./requireOrError")
 const config = require("../config")
 const inliningCss = require("./inliningCss")
+const { validateCssModulesConfig } = require("./validateCssModulesConfig")
 
 const getStyleRule = (test, preprocessors = []) => {
   if (moduleExists("css-loader")) {
@@ -19,17 +20,25 @@ const getStyleRule = (test, preprocessors = []) => {
         ? requireOrError("@rspack/core").CssExtractRspackPlugin.loader
         : requireOrError("mini-css-extract-plugin").loader
 
+    const cssLoaderOptions = {
+      sourceMap: true,
+      importLoaders: 2,
+      modules: {
+        auto: true,
+        // v9 defaults: named exports with camelCase conversion
+        namedExport: true,
+        exportLocalsConvention: "camelCase"
+      }
+    }
+
+    // Validate CSS modules configuration
+    validateCssModulesConfig(cssLoaderOptions)
+
     const use = [
       inliningCss ? "style-loader" : extractionPlugin,
       {
         loader: require.resolve("css-loader"),
-        options: {
-          sourceMap: true,
-          importLoaders: 2,
-          modules: {
-            auto: true
-          }
-        }
+        options: cssLoaderOptions
       },
       tryPostcss(),
       ...preprocessors