shakapacker 9.3.0.beta.1 → 9.3.0.beta.4

data/docs/v9_upgrade.md

@@ -4,6 +4,15 @@ This guide outlines new features, breaking changes, and migration steps for upgr
 
 **📖 For detailed configuration options, see the [Configuration Guide](./configuration.md)**
 
+> **⚠️ Important:** Shakapacker is both a Ruby gem AND an npm package. **You must update BOTH**:
+>
+> - Update the version in `Gemfile`
+> - Update the version in `package.json`
+> - Run `bundle update shakapacker`
+> - Run your package manager install command (`yarn install`, `npm install`, or `pnpm install`)
+>
+> See [Migration Steps](#migration-steps) below for detailed instructions including version format differences and testing.
+
 > **⚠️ Important for v9.1.0 Users:** If you're upgrading to v9.1.0 or later, please note the [SWC Configuration Breaking Change](#swc-loose-mode-breaking-change-v910) below. This affects users who previously configured SWC in v9.0.0.
 
 ## New Features
@@ -264,15 +273,49 @@ You won't get warnings about missing Babel, Rspack, or esbuild packages.
 
 ## Migration Steps
 
-### Step 1: Update Dependencies
+> **💡 Tip:** For general upgrade instructions applicable to all Shakapacker versions, see [Upgrading Shakapacker](./common-upgrades.md#upgrading-shakapacker) in the Common Upgrades guide.
+
+### Step 1: Update Gemfile
+
+Update the shakapacker version in your `Gemfile`:
+
+```ruby
+# Gemfile
+gem "shakapacker", "9.3.0"  # or latest version
+```
+
+**Note:** Ruby gems use dot notation for pre-release versions (e.g., `9.3.0.beta.1`), while npm uses hyphen notation (e.g., `9.3.0-beta.1`). See [Version Format Differences](#version-format-differences) below.
+
+### Step 2: Update package.json
+
+Update the shakapacker version in your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "shakapacker": "9.3.0"
+  }
+}
+```
+
+**Note:** For pre-release versions, npm uses hyphen notation (e.g., `"shakapacker": "9.3.0-beta.1"`).
+
+### Step 3: Install Updates
+
+Run both bundler and your package manager:
 
 ```bash
-npm update shakapacker@^9.0.0
-# or
-yarn upgrade shakapacker@^9.0.0
+# Update Ruby gem
+bundle update shakapacker
+
+# Update npm package (choose one based on your package manager)
+yarn install      # if using Yarn
+npm install       # if using npm
+pnpm install      # if using pnpm
+bun install       # if using Bun
 ```
 
-### Step 2: Update CSS Module Imports
+### Step 4: Update CSS Module Imports
 
 #### For each CSS module import:
 
@@ -299,7 +342,7 @@ declare module "*.module.css" {
 }
 ```
 
-### Step 3: Handle Kebab-Case Class Names
+### Step 5: Handle Kebab-Case Class Names
 
 v9 automatically converts kebab-case to camelCase with `exportLocalsConvention: 'camelCaseOnly'`:
 
@@ -340,7 +383,7 @@ 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
+### Step 6: Update Configuration Files
 
 If you have `webpack_loader` in your configuration:
 
@@ -353,7 +396,7 @@ If you have `webpack_loader` in your configuration:
 javascript_transpiler: "babel"
 ```
 
-### Step 5: Run Tests
+### Step 7: Run Tests
 
 ```bash
 # Run your test suite
@@ -366,6 +409,45 @@ bin/shakapacker
 bin/shakapacker-dev-server
 ```
 
+## Version Format Differences
+
+Shakapacker version numbers differ between the Ruby gem and npm package for pre-release versions:
+
+| Version Type | Ruby Gem (Gemfile) | npm Package (package.json) |
+| ------------ | ------------------ | -------------------------- |
+| Stable       | `"9.3.0"`          | `"9.3.0"`                  |
+| Pre-release  | `"9.3.0.beta.1"`   | `"9.3.0-beta.1"`           |
+
+**Examples:**
+
+```ruby
+# Gemfile - uses dots for pre-release versions
+gem "shakapacker", "9.3.0"         # stable
+gem "shakapacker", "9.3.0.beta.1"  # pre-release
+```
+
+Stable version in package.json:
+
+```json
+{
+  "dependencies": {
+    "shakapacker": "9.3.0"
+  }
+}
+```
+
+Pre-release version in package.json:
+
+```json
+{
+  "dependencies": {
+    "shakapacker": "9.3.0-beta.1"
+  }
+}
+```
+
+This is due to different versioning conventions between RubyGems (which uses dots) and npm (which follows semantic versioning with hyphens for pre-release identifiers).
+
 ## Troubleshooting
 
 ### CSS Classes Not Applying

data/eslint.config.js

@@ -14,11 +14,16 @@ module.exports = [
   // Global ignores (replaces .eslintignore)
   {
     ignores: [
-      "lib/**",
-      "**/node_modules/**",
-      "vendor/**",
-      "spec/**",
-      "package/**" // TODO: Remove after issue #644 is resolved (lints package/ TS source files)
+      "lib/**", // Ruby files, not JavaScript
+      "**/node_modules/**", // Third-party dependencies
+      "vendor/**", // Vendored dependencies
+      "spec/**", // Ruby specs, not JavaScript
+      "package/**/*.js", // Generated/compiled JavaScript from TypeScript
+      "package/**/*.d.ts", // Generated TypeScript declaration files
+      // Temporarily ignore TypeScript files until technical debt is resolved
+      // See ESLINT_TECHNICAL_DEBT.md for tracking
+      // TODO: Remove this once ESLint issues are fixed (tracked in #723)
+      "package/**/*.ts"
     ]
   },
 
@@ -52,7 +57,11 @@ module.exports = [
       "import/no-extraneous-dependencies": "off",
       // TypeScript handles extensions, not needed for JS imports
       "import/extensions": "off",
-      indent: ["error", 2]
+      indent: ["error", 2],
+      // Allow for...of loops - modern JS syntax, won't pollute client code
+      "no-restricted-syntax": "off",
+      // Allow console statements - used for debugging/logging throughout
+      "no-console": "off"
     },
     settings: {
       react: {
@@ -131,7 +140,110 @@ module.exports = [
       // Strict: no 'any' types allowed - use 'unknown' or specific types instead
       "@typescript-eslint/no-explicit-any": "error",
       // Allow implicit return types - TypeScript can infer them
-      "@typescript-eslint/explicit-module-boundary-types": "off"
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+      // Disable no-undef for TypeScript - TypeScript compiler handles this
+      // This prevents false positives for ambient types like NodeJS.ProcessEnv
+      "no-undef": "off"
+    }
+  },
+
+  // Temporary overrides for files with remaining errors
+  // See ESLINT_TECHNICAL_DEBT.md for detailed documentation
+  //
+  // These overrides suppress ~172 errors that require either:
+  // 1. Major type refactoring (any/unsafe-* rules)
+  // 2. Potential breaking changes (module system)
+  // 3. Significant code restructuring
+  //
+  // GitHub Issues tracking this technical debt:
+  // - #707: TypeScript: Refactor configExporter module for type safety
+  // - #708: Module System: Modernize to ES6 modules with codemod
+  // - #709: Code Style: Fix remaining ESLint style issues
+  {
+    // Consolidated override for package/config.ts and package/babel/preset.ts
+    // Combines rules from both previous override blocks to avoid duplication
+    files: ["package/babel/preset.ts", "package/config.ts"],
+    rules: {
+      // From first override block
+      "@typescript-eslint/no-require-imports": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "import/order": "off",
+      "import/newline-after-import": "off",
+      "import/first": "off",
+      // Additional rules that were in the second override for config.ts
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "no-useless-escape": "off",
+      "no-continue": "off"
+    }
+  },
+  {
+    files: ["package/configExporter/**/*.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-function-type": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "@typescript-eslint/require-await": "off",
+      "no-await-in-loop": "off",
+      "import/prefer-default-export": "off",
+      "global-require": "off",
+      "no-underscore-dangle": "off"
+    }
+  },
+  {
+    // Remaining utils files (removed package/config.ts from this block)
+    files: [
+      "package/utils/inliningCss.ts",
+      "package/utils/errorCodes.ts",
+      "package/utils/errorHelpers.ts",
+      "package/utils/pathValidation.ts"
+    ],
+    rules: {
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "no-useless-escape": "off",
+      "no-continue": "off"
+    }
+  },
+  {
+    files: ["package/plugins/**/*.ts", "package/optimization/**/*.ts"],
+    rules: {
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-redundant-type-constituents": "off",
+      "import/prefer-default-export": "off"
+    }
+  },
+  {
+    files: [
+      "package/environments/**/*.ts",
+      "package/index.ts",
+      "package/rspack/index.ts",
+      "package/rules/**/*.ts",
+      "package/swc/index.ts",
+      "package/esbuild/index.ts",
+      "package/dev_server.ts",
+      "package/env.ts"
+    ],
+    rules: {
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+      "@typescript-eslint/no-redundant-type-constituents": "off",
+      "@typescript-eslint/no-unused-vars": "off",
+      "@typescript-eslint/no-unsafe-function-type": "off",
+      "import/prefer-default-export": "off",
+      "no-underscore-dangle": "off"
     }
   },
 

data/lib/shakapacker/build_config_loader.rb

@@ -0,0 +1,147 @@
+require "yaml"
+
+module Shakapacker
+  class BuildConfigLoader
+    attr_reader :config_file_path
+
+    def initialize(config_file_path = nil)
+      @config_file_path = config_file_path || File.join(Dir.pwd, "config", "shakapacker-builds.yml")
+    end
+
+    def exists?
+      File.exist?(@config_file_path)
+    end
+
+    def load_build(build_name)
+      unless exists?
+        raise ArgumentError, "Config file not found: #{@config_file_path}\n" \
+                            "Run 'bin/shakapacker --init' to generate a sample config file."
+      end
+
+      config = load_config
+      fetch_build_or_raise(config, build_name)
+    end
+
+    def resolve_build_config(build_name, default_bundler: "webpack")
+      config = load_config
+      build = fetch_build_or_raise(config, build_name)
+
+      # Resolve bundler with precedence: build.bundler > config.default_bundler > default_bundler
+      bundler = build["bundler"] || config["default_bundler"] || default_bundler
+
+      # Get environment variables
+      environment = build["environment"] || {}
+
+      # Get config file path if specified
+      config_file = build["config"]
+      if config_file
+        # Expand ${BUNDLER} variable
+        config_file = config_file.gsub("${BUNDLER}", bundler)
+      end
+
+      # Get bundler_env for --env flags
+      bundler_env = build["bundler_env"] || {}
+
+      # Get outputs
+      outputs = build["outputs"] || []
+
+      # Validate outputs
+      if outputs.empty?
+        raise ArgumentError, "Build '#{build_name}' has empty outputs array. " \
+                            "Please specify at least one output type (client, server, or all)."
+      end
+
+      {
+        name: build_name,
+        description: build["description"],
+        bundler: bundler,
+        dev_server: build["dev_server"],
+        environment: environment,
+        bundler_env: bundler_env,
+        outputs: outputs,
+        config_file: config_file
+      }
+    end
+
+    def uses_dev_server?(build_config)
+      # Check explicit dev_server flag first (preferred)
+      # Only return early if the value is explicitly set (not nil)
+      return build_config[:dev_server] unless build_config[:dev_server].nil?
+
+      # Fallback: check environment variables for backward compatibility
+      env = build_config[:environment]
+      return false unless env
+
+      # Handle both string "true" and boolean true from YAML
+      %w[WEBPACK_SERVE HMR].any? do |key|
+        value = env[key]
+        value.to_s.strip.casecmp("true").zero?
+      end
+    end
+
+    def list_builds
+      config = load_config
+      builds = config["builds"]
+
+      puts "\nAvailable builds in #{@config_file_path}:\n\n"
+
+      builds.each do |name, build|
+        bundler = build["bundler"] || config["default_bundler"] || "webpack (default)"
+        outputs = build["outputs"] ? build["outputs"].join(", ") : "missing (invalid)"
+
+        puts "  #{name}"
+        puts "    Description: #{build["description"]}" if build["description"]
+        puts "    Bundler: #{bundler}"
+        puts "    Outputs: #{outputs}"
+        puts ""
+      end
+    end
+
+    private
+
+      def fetch_build_or_raise(config, build_name)
+        build = config["builds"][build_name]
+        unless build
+          available = config["builds"].keys.join(", ")
+          raise ArgumentError, "Build '#{build_name}' not found in config file.\n" \
+                              "Available builds: #{available}\n" \
+                              "Use 'bin/shakapacker --list-builds' to see all available builds."
+        end
+        build
+      end
+
+      # Load YAML config file safely with Ruby version compatibility
+      # Ruby 3.1+ supports safe_load_file with aliases, older versions need safe_load
+      def load_config
+        begin
+          config = if YAML.respond_to?(:safe_load_file)
+            # Ruby 3.1+: Use safe_load_file with aliases enabled
+            YAML.safe_load_file(@config_file_path, aliases: true)
+          else
+            # Ruby 2.7-3.0: Use safe_load with aliases enabled
+            YAML.safe_load(
+              File.read(@config_file_path),
+              permitted_classes: [],
+              permitted_symbols: [],
+              aliases: true
+            )
+          end
+        rescue ArgumentError
+          # Fallback for older Psych versions without aliases support
+          config = YAML.safe_load(
+            File.read(@config_file_path),
+            permitted_classes: [],
+            permitted_symbols: []
+          )
+        end
+
+        unless config["builds"]&.is_a?(Hash)
+          raise ArgumentError, "Config file must contain a 'builds' object"
+        end
+
+        config
+      rescue Psych::SyntaxError => e
+        raise ArgumentError, "Invalid YAML in config file: #{e.message}"
+      end
+  end
+end

data/lib/shakapacker/configuration.rb

@@ -8,12 +8,13 @@ class Shakapacker::Configuration
     attr_accessor :installing
   end
 
-  attr_reader :root_path, :config_path, :env
+  attr_reader :root_path, :config_path, :env, :bundler_override
 
-  def initialize(root_path:, config_path:, env:)
+  def initialize(root_path:, config_path:, env:, bundler_override: nil)
     @root_path = root_path
     @env = env
     @config_path = config_path
+    @bundler_override = bundler_override
   end
 
   def dev_server
@@ -97,6 +98,9 @@ class Shakapacker::Configuration
   end
 
   def assets_bundler
+    # CLI --bundler flag takes highest precedence
+    return @bundler_override if @bundler_override
+
     # 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."

data/lib/shakapacker/dev_server_runner.rb

@@ -18,9 +18,71 @@ module Shakapacker
         exit(0)
       end
 
+      # Check for --build flag
+      build_index = argv.index("--build")
+      if build_index
+        build_name = argv[build_index + 1]
+
+        unless build_name
+          $stderr.puts "[Shakapacker] Error: --build requires a build name"
+          $stderr.puts "Usage: bin/shakapacker-dev-server --build <name>"
+          exit(1)
+        end
+
+        loader = BuildConfigLoader.new
+
+        unless loader.exists?
+          $stderr.puts "[Shakapacker] Config file not found: #{loader.config_file_path}"
+          $stderr.puts "Run 'bin/shakapacker --init' to create one"
+          exit(1)
+        end
+
+        begin
+          build_config = loader.resolve_build_config(build_name)
+
+          # Check if this build is meant for dev server
+          unless loader.uses_dev_server?(build_config)
+            $stderr.puts "[Shakapacker] Error: Build '#{build_name}' is not configured for dev server (dev_server: false)"
+            $stderr.puts "[Shakapacker] Use this command instead:"
+            $stderr.puts "  bin/shakapacker --build #{build_name}"
+            exit(1)
+          end
+
+          # Remove --build and build name from argv
+          remaining_argv = argv.dup
+          remaining_argv.delete_at(build_index + 1)
+          remaining_argv.delete_at(build_index)
+
+          run_with_build_config(remaining_argv, build_config)
+          return
+        rescue ArgumentError => e
+          $stderr.puts "[Shakapacker] #{e.message}"
+          exit(1)
+        end
+      end
+
       new(argv).run
     end
 
+    def self.run_with_build_config(argv, build_config)
+      # Apply build config environment variables
+      build_config[:environment].each do |key, value|
+        ENV[key] = value.to_s
+      end
+
+      # Set SHAKAPACKER_ASSETS_BUNDLER so JS/TS config files use the correct bundler
+      # This ensures the bundler override (from --bundler or build config) is respected
+      ENV["SHAKAPACKER_ASSETS_BUNDLER"] = build_config[:bundler]
+
+      puts "[Shakapacker] Running dev server for build: #{build_config[:name]}"
+      puts "[Shakapacker] Description: #{build_config[:description]}" if build_config[:description]
+      puts "[Shakapacker] Bundler: #{build_config[:bundler]}"
+      puts "[Shakapacker] Config file: #{build_config[:config_file]}" if build_config[:config_file]
+
+      # Pass bundler override so Configuration.assets_bundler reflects the build
+      new(argv, build_config, build_config[:bundler]).run
+    end
+
     def self.print_help
       puts <<~HELP
         ================================================================================
@@ -33,6 +95,17 @@ module Shakapacker
           -h, --help              Show this help message
           -v, --version           Show Shakapacker version
           --debug-shakapacker     Enable Node.js debugging (--inspect-brk)
+          --build <name>          Run a specific build configuration
+
+        Build configurations (config/shakapacker-builds.yml):
+          bin/shakapacker-dev-server --build dev-hmr    # Run the 'dev-hmr' build
+
+          To manage builds:
+          bin/shakapacker --init                        # Create config file
+          bin/shakapacker --list-builds                 # List available builds
+
+          Note: You can also use bin/shakapacker --build with a build that has
+          WEBPACK_SERVE=true, and it will automatically use the dev server.
 
         Examples:
           bin/shakapacker-dev-server                    # Start dev server