shakapacker 8.4.0 → 9.7.0

data/lib/tasks/shakapacker/check_binstubs.rake

@@ -11,8 +11,8 @@ def verify_file_existence(binstub_file)
     puts <<~MSG
       Couldn't find shakapacker binstubs!
       Possible solutions:
-      - Ensure you have run `rails shakapacker:install`.
-      - Run `rails shakapacker:binstubs` if you have already installed shakapacker.
+      - Ensure you have run `bundle exec rake shakapacker:install`.
+      - Run `bundle exec rake shakapacker:binstubs` if you have already installed shakapacker.
       - Ensure the `bin` directory, `bin/shakapacker`, and `bin/shakapacker-dev-server` are not included in .gitignore.
     MSG
     exit!

data/lib/tasks/shakapacker/doctor.rake

@@ -0,0 +1,48 @@
+require "shakapacker/doctor"
+
+namespace :shakapacker do
+  desc <<~DESC
+    Checks for common Shakapacker configuration issues and missing dependencies
+
+    Performs comprehensive diagnostics including:
+    • Configuration file validity and deprecated settings
+    • Entry points, output paths, and asset compilation status
+    • Node.js and package manager installation
+    • Required and optional npm dependencies
+    • JavaScript transpiler (Babel, SWC, esbuild) configuration
+    • CSS, CSS Modules, and stylesheet preprocessor setup
+    • Binstubs presence (shakapacker, shakapacker-dev-server, shakapacker-config)
+    • Version consistency between gem and npm package
+    • Legacy Webpacker file detection
+
+    Options:
+      --help       Show detailed help and usage information
+      --verbose    Display additional diagnostic details (paths, versions, environment)
+
+    Examples:
+      bundle exec rake shakapacker:doctor
+      bundle exec rake shakapacker:doctor -- --verbose
+      bundle exec rake shakapacker:doctor -- --help
+
+    Exit codes:
+      0 - No issues found
+      1 - Issues or warnings detected (see output for details)
+  DESC
+  task doctor: :environment do
+    # Parse command-line options
+    options = {}
+    ARGV.each do |arg|
+      case arg
+      when "--help", "-h"
+        options[:help] = true
+      when "--verbose", "-v"
+        options[:verbose] = true
+      end
+    end
+
+    Shakapacker::Doctor.new(nil, nil, options).run
+
+    # Prevent rake from treating options as task names
+    ARGV.each { |arg| task arg.to_sym do; end if arg.start_with?("--", "-") }
+  end
+end

data/lib/tasks/shakapacker/export_bundler_config.rake

@@ -0,0 +1,68 @@
+namespace :shakapacker do
+  desc <<~DESC
+    Export webpack or rspack configuration for debugging and analysis
+
+    Exports your resolved webpack/rspack configuration in human-readable formats.
+    Use this to debug configuration issues, compare environments, or analyze
+    client vs server bundle differences.
+
+    Usage:
+      rake shakapacker:export_bundler_config -- [OPTIONS]
+
+    Quick Start (Recommended):
+      rails shakapacker:export_bundler_config --doctor
+
+    This exports all configs (dev + prod, client + server) to shakapacker-config-exports/
+    directory in annotated YAML format - perfect for troubleshooting.
+
+    Common Options:
+      --doctor              Export everything for troubleshooting (recommended)
+      --save                Save current environment configs to files
+      --save-dir=<dir>      Custom output directory (requires --save)
+      --env=development|production|test    Specify environment
+      --client-only         Export only client config
+      --server-only         Export only server config
+      --format=yaml|json|inspect           Output format
+      --help, -h            Show detailed help
+
+    Examples:
+      # Export all configs for troubleshooting
+      bundle exec rake shakapacker:export_bundler_config -- --doctor
+
+      # Save production client config
+      bundle exec rake shakapacker:export_bundler_config -- --save --env=production --client-only
+
+      # View development config in terminal
+      bundle exec rake shakapacker:export_bundler_config
+
+      # Show detailed help
+      bundle exec rake shakapacker:export_bundler_config -- --help
+
+    The task automatically falls back to the gem version if bin/shakapacker-config
+    binstub is not installed. To install all binstubs, run: bundle exec rake shakapacker:binstubs
+  DESC
+  task :export_bundler_config do
+    # Try to use the binstub if it exists, otherwise use the gem's version
+    bin_path = Rails.root.join("bin/shakapacker-config")
+
+    unless File.exist?(bin_path)
+      # Binstub not installed, use the gem's version directly
+      gem_bin_path = File.expand_path("../../install/bin/shakapacker-config", __dir__)
+
+      $stderr.puts "Note: bin/shakapacker-config binstub not found."
+      $stderr.puts "Using gem version directly. To install the binstub, run: rake shakapacker:binstubs"
+      $stderr.puts ""
+
+      Dir.chdir(Rails.root) do
+        exec("node", gem_bin_path, *ARGV[1..])
+      end
+    else
+      # Pass through command-line arguments after the task name
+      # Use exec to replace the rake process with the export script
+      # This ensures proper exit codes and signal handling
+      Dir.chdir(Rails.root) do
+        exec(bin_path.to_s, *ARGV[1..])
+      end
+    end
+  end
+end

data/lib/tasks/shakapacker/install.rake

@@ -2,16 +2,28 @@ install_template_path = File.expand_path("../../install/template.rb", __dir__).f
 bin_path = ENV["BUNDLE_BIN"] || Rails.root.join("bin")
 
 namespace :shakapacker do
-  desc "Install Shakapacker in this application"
-  task install: [:check_node] do |task|
+  desc "Install Shakapacker in this application (use SHAKAPACKER_ASSETS_BUNDLER=rspack for Rspack, --typescript for TypeScript)"
+  task :install, [:bundler, :typescript] => [:check_node] do |task, args|
     Shakapacker::Configuration.installing = true
 
+    if args[:bundler] == "rspack" || ENV["SHAKAPACKER_ASSETS_BUNDLER"] == "rspack"
+      ENV["SHAKAPACKER_ASSETS_BUNDLER"] = "rspack"
+    end
+
+    # Set typescript flag if passed as argument
+    # Accepts: typescript, true, or any truthy value
+    if args[:typescript] && args[:typescript] != "false"
+      ENV["SHAKAPACKER_USE_TYPESCRIPT"] = "true"
+    end
+
     prefix = task.name.split(/#|shakapacker:install/).first
 
     if Rails::VERSION::MAJOR >= 5
-      exec "#{RbConfig.ruby} '#{bin_path}/rails' #{prefix}app:template LOCATION='#{install_template_path}'"
+      system "#{RbConfig.ruby} '#{bin_path}/rails' #{prefix}app:template LOCATION='#{install_template_path}'" or
+        raise "Installation failed"
     else
-      exec "#{RbConfig.ruby} '#{bin_path}/rake' #{prefix}rails:template LOCATION='#{install_template_path}'"
+      system "#{RbConfig.ruby} '#{bin_path}/rake' #{prefix}rails:template LOCATION='#{install_template_path}'" or
+        raise "Installation failed"
     end
   end
 end

data/lib/tasks/shakapacker/migrate_to_swc.rake

@@ -0,0 +1,13 @@
+require "shakapacker/swc_migrator"
+
+namespace :shakapacker do
+  desc "Migrate from Babel to SWC transpiler"
+  task :migrate_to_swc do
+    Shakapacker::SwcMigrator.new(Rails.root).migrate_to_swc
+  end
+
+  desc "Remove Babel packages after migrating to SWC"
+  task :clean_babel_packages do
+    Shakapacker::SwcMigrator.new(Rails.root).clean_babel_packages
+  end
+end

data/lib/tasks/shakapacker/switch_bundler.rake

@@ -0,0 +1,72 @@
+require "shakapacker/bundler_switcher"
+
+namespace :shakapacker do
+  desc <<~DESC
+    Switch between webpack and rspack bundlers
+
+    Easily switch your Shakapacker configuration between webpack and rspack bundlers.
+    This task updates config/shakapacker.yml and optionally manages npm dependencies.
+
+    Usage:
+      bin/rake shakapacker:switch_bundler [webpack|rspack] -- [OPTIONS]
+
+    Options:
+      --install-deps    Automatically install/uninstall bundler dependencies
+      --no-uninstall    Skip uninstalling old bundler packages
+      --init-config     Create custom dependencies configuration file
+      --help, -h        Show detailed help message
+
+    Examples:
+      bin/rake shakapacker:switch_bundler rspack -- --install-deps
+      bin/rake shakapacker:switch_bundler webpack -- --install-deps --no-uninstall
+      bin/rake shakapacker:switch_bundler -- --init-config
+      bin/rake shakapacker:switch_bundler -- --help
+
+    What it does:
+      - Updates 'assets_bundler' in config/shakapacker.yml
+      - Preserves YAML comments and structure
+      - Updates 'javascript_transpiler' to 'swc' when switching to rspack
+      - With --install-deps: installs/uninstalls npm dependencies automatically
+      - Without: shows manual installation commands
+
+    Custom Dependencies:
+      Create .shakapacker-switch-bundler-dependencies.yml to customize which
+      npm packages are installed/uninstalled during bundler switching.
+
+    See docs/rspack_migration_guide.md for more information.
+  DESC
+  task :switch_bundler do
+    # This task must be run with rake, not rails
+    # Check the actual command name, not just if the path contains "rails"
+    command_name = File.basename($0)
+    if command_name == "rails" || $0.end_with?("/rails")
+      puts "\nError: This task must be run with 'bin/rake', not 'bin/rails'"
+      puts "Usage: bin/rake shakapacker:switch_bundler [bundler] -- [options]"
+      puts "Run 'bin/rake shakapacker:switch_bundler -- --help' for more information"
+      exit 1
+    end
+
+    switcher = Shakapacker::BundlerSwitcher.new
+
+    # Parse command line arguments
+    # ARGV[0] is the task name, ARGV[1] would be the bundler name if provided
+    bundler = ARGV.length > 1 ? ARGV[1] : nil
+    install_deps = ARGV.include?("--install-deps")
+    no_uninstall = ARGV.include?("--no-uninstall")
+    init_config = ARGV.include?("--init-config")
+    show_help = ARGV.include?("--help") || ARGV.include?("-h")
+
+    if ARGV.empty? || show_help || (bundler.nil? && !init_config)
+      switcher.show_usage
+    elsif init_config
+      switcher.init_config
+    elsif bundler.nil? || bundler.start_with?("-")
+      switcher.show_usage
+    else
+      switcher.switch_to(bundler, install_deps: install_deps, no_uninstall: no_uninstall)
+    end
+
+    # Prevent rake from trying to execute arguments as tasks
+    ARGV.each { |arg| task arg.to_sym {} }
+  end
+end

data/lib/tasks/shakapacker.rake

@@ -9,6 +9,8 @@ tasks = {
   "shakapacker:check_binstubs"          => "Verifies that bin/shakapacker is present",
   "shakapacker:binstubs"                => "Installs Shakapacker binstubs in this application",
   "shakapacker:verify_install"          => "Verifies if Shakapacker is installed",
+  "shakapacker:doctor"                  => "Checks for configuration issues and missing dependencies",
+  "shakapacker:switch_bundler"          => "Switch between webpack and rspack bundlers"
 }.freeze
 
 desc "Lists all available tasks in Shakapacker"

data/package/.npmignore

@@ -0,0 +1,4 @@
+# Exclude TypeScript source files from the package directory
+*.ts
+# But keep the TypeScript declaration files
+!*.d.ts

data/package/babel/preset.ts

@@ -0,0 +1,59 @@
+import { moduleExists, packageFullVersion } from "../utils/helpers"
+import type { ConfigAPI, PluginItem } from "@babel/core"
+
+const CORE_JS_VERSION_REGEX = /^\d+\.\d+/
+
+const coreJsVersion = (): string => {
+  try {
+    const version = packageFullVersion("core-js").match(CORE_JS_VERSION_REGEX)
+    return version?.[0] ?? "3.8"
+  } catch (e) {
+    const error = e as NodeJS.ErrnoException
+    if (error.code !== "MODULE_NOT_FOUND") {
+      throw e
+    }
+
+    return "3.8"
+  }
+}
+
+export = function config(api: ConfigAPI): {
+  presets: PluginItem[]
+  plugins: PluginItem[]
+} {
+  const validEnv = ["development", "test", "production"]
+  const currentEnv = api.env()
+  const isDevelopmentEnv = api.env("development")
+  const isProductionEnv = api.env("production")
+  const isTestEnv = api.env("test")
+
+  if (!validEnv.includes(currentEnv)) {
+    throw new Error(
+      `Please specify a valid NODE_ENV or BABEL_ENV environment variable. Valid values are "development", "test", and "production". Instead, received: "${currentEnv}".`
+    )
+  }
+
+  const presets: PluginItem[] = [
+    isTestEnv && ["@babel/preset-env", { targets: { node: "current" } }],
+    (isProductionEnv || isDevelopmentEnv) && [
+      "@babel/preset-env",
+      {
+        useBuiltIns: "entry",
+        corejs: coreJsVersion(),
+        modules: "auto",
+        bugfixes: true,
+        exclude: ["transform-typeof-symbol"]
+      }
+    ],
+    moduleExists("@babel/preset-typescript") && "@babel/preset-typescript"
+  ].filter(Boolean) as PluginItem[]
+
+  const plugins: PluginItem[] = [
+    ["@babel/plugin-transform-runtime", { helpers: false }]
+  ].filter(Boolean) as PluginItem[]
+
+  return {
+    presets,
+    plugins
+  }
+}

data/package/config.ts

@@ -0,0 +1,189 @@
+import { resolve } from "path"
+import { load } from "js-yaml"
+import { existsSync, readFileSync } from "fs"
+import { merge } from "webpack-merge"
+const { ensureTrailingSlash } = require("./utils/helpers")
+const { railsEnv } = require("./env")
+const configPath = require("./utils/configPath")
+const defaultConfigPath = require("./utils/defaultConfigPath")
+import { Config, YamlConfig } from "./types"
+const {
+  isValidYamlConfig,
+  createConfigValidationError,
+  isPartialConfig
+} = require("./utils/typeGuards")
+const {
+  isFileNotFoundError,
+  createFileOperationError
+} = require("./utils/errorHelpers")
+
+const loadAndValidateYaml = (path: string): YamlConfig => {
+  const fileContent = readFileSync(path, "utf8")
+  const yamlContent = load(fileContent)
+
+  if (!isValidYamlConfig(yamlContent)) {
+    throw createConfigValidationError(path, railsEnv, "Invalid YAML structure")
+  }
+
+  return yamlContent as YamlConfig
+}
+
+const getDefaultConfig = (): Partial<Config> => {
+  try {
+    const defaultConfig = loadAndValidateYaml(defaultConfigPath)
+    return defaultConfig[railsEnv] || defaultConfig.production || {}
+  } catch (error) {
+    if (isFileNotFoundError(error)) {
+      throw createFileOperationError(
+        "read",
+        defaultConfigPath,
+        `Default configuration not found at ${defaultConfigPath}. Please ensure Shakapacker is properly installed. You may need to run 'yarn add shakapacker' or 'npm install shakapacker'.`
+      )
+    }
+    throw error
+  }
+}
+
+const defaults = getDefaultConfig()
+let config: Config
+
+if (existsSync(configPath)) {
+  try {
+    const appYmlObject = loadAndValidateYaml(configPath)
+
+    const envAppConfig = appYmlObject[railsEnv]
+
+    if (!envAppConfig) {
+      console.warn(
+        `[SHAKAPACKER WARNING] Environment '${railsEnv}' not found in ${configPath}\n` +
+          `Available environments: ${Object.keys(appYmlObject).join(", ")}\n` +
+          `Using 'production' configuration as fallback.\n\n` +
+          `To fix this, either:\n` +
+          `  - Add a '${railsEnv}' section to your shakapacker.yml\n` +
+          `  - Set RAILS_ENV to one of the available environments\n` +
+          `  - Copy settings from another environment as a starting point`
+      )
+    }
+
+    // Merge returns the merged type
+    const mergedConfig = merge(defaults, envAppConfig || {})
+
+    // Validate merged config before type assertion
+    if (!isPartialConfig(mergedConfig)) {
+      throw createConfigValidationError(
+        configPath,
+        railsEnv,
+        `Invalid configuration structure in ${configPath}. Please check your shakapacker.yml syntax and ensure all required fields are properly defined.`
+      )
+    }
+
+    // After merging with defaults, config should be complete
+    // Use type assertion only after validation
+    config = mergedConfig as Config
+  } catch (error) {
+    if (isFileNotFoundError(error)) {
+      // File not found is OK, use defaults
+      if (!isPartialConfig(defaults)) {
+        throw createConfigValidationError(
+          defaultConfigPath,
+          railsEnv,
+          `Invalid default configuration. This may indicate a corrupted Shakapacker installation. Try reinstalling with 'yarn add shakapacker --force'.`
+        )
+      }
+      // Using defaults only, might be partial
+      config = defaults as Config
+    } else {
+      throw error
+    }
+  }
+} else {
+  // No user config, use defaults
+  if (!isPartialConfig(defaults)) {
+    throw createConfigValidationError(
+      defaultConfigPath,
+      railsEnv,
+      `Invalid default configuration. This may indicate a corrupted Shakapacker installation. Try reinstalling with 'yarn add shakapacker --force'.`
+    )
+  }
+  // Using defaults only, might be partial
+  config = defaults as Config
+}
+
+config.outputPath = resolve(config.public_root_path, config.public_output_path)
+
+if (config.private_output_path) {
+  config.privateOutputPath = resolve(config.private_output_path)
+}
+
+// Ensure that the publicPath includes our asset host so dynamic imports
+// (code-splitting chunks and static assets) load from the CDN instead of a relative path.
+const getPublicPath = (): string => {
+  const rootUrl = ensureTrailingSlash(process.env.SHAKAPACKER_ASSET_HOST || "/")
+  return `${rootUrl}${config.public_output_path}/`
+}
+
+config.publicPath = getPublicPath()
+config.publicPathWithoutCDN = `/${config.public_output_path}/`
+
+if (config.manifest_path) {
+  config.manifestPath = resolve(config.manifest_path)
+} else {
+  config.manifestPath = resolve(config.outputPath, "manifest.json")
+}
+// Ensure no duplicate hash functions exist in the returned config object
+if (config.integrity?.hash_functions) {
+  config.integrity.hash_functions = [
+    ...new Set(config.integrity.hash_functions)
+  ]
+}
+
+// Ensure assets_bundler has a default value
+if (!config.assets_bundler) {
+  config.assets_bundler = "webpack"
+}
+
+// Allow ENV variable to override assets_bundler
+if (process.env.SHAKAPACKER_ASSETS_BUNDLER) {
+  config.assets_bundler = process.env.SHAKAPACKER_ASSETS_BUNDLER
+}
+
+// Define clear defaults
+// Keep Babel as default for webpack to maintain backward compatibility
+// Use SWC for rspack as it's a newer bundler where we can set modern defaults
+const DEFAULT_JAVASCRIPT_TRANSPILER =
+  config.assets_bundler === "rspack" ? "swc" : "babel"
+
+// Backward compatibility: Check for webpack_loader using proper type guard
+function hasWebpackLoader(
+  obj: unknown
+): obj is Config & { webpack_loader: string } {
+  return (
+    typeof obj === "object" &&
+    obj !== null &&
+    "webpack_loader" in obj &&
+    typeof (obj as Record<string, unknown>).webpack_loader === "string"
+  )
+}
+
+// Allow environment variable to override javascript_transpiler
+if (process.env.SHAKAPACKER_JAVASCRIPT_TRANSPILER) {
+  config.javascript_transpiler = process.env.SHAKAPACKER_JAVASCRIPT_TRANSPILER
+} else if (hasWebpackLoader(config) && !config.javascript_transpiler) {
+  console.warn(
+    "[SHAKAPACKER DEPRECATION] The 'webpack_loader' configuration option is deprecated.\n" +
+      "Please use 'javascript_transpiler' instead as it better reflects its purpose of configuring JavaScript transpilation regardless of the bundler used."
+  )
+  config.javascript_transpiler = config.webpack_loader
+} else if (!config.javascript_transpiler) {
+  config.javascript_transpiler = DEFAULT_JAVASCRIPT_TRANSPILER
+}
+
+// Ensure webpack_loader is always available for backward compatibility
+Object.defineProperty(config, "webpack_loader", {
+  value: config.javascript_transpiler,
+  writable: true,
+  enumerable: true,
+  configurable: true
+})
+
+export = config