shakapacker 9.1.0 → 9.3.0.beta.0

data/docs/v8_upgrade.md

@@ -18,6 +18,7 @@ If you are not using CDN, then this change will have no effect on your setup.
 If you are using CDN and your CDN host is static, `config.asset_host` setting in Rails will be respected during compilation and when referencing assets through view helpers.
 
 If your host might differ, between various environments for example, you will either need to:
+
 - Ensure the assets are specifically rebuilt for each environment (Heroku pipeline promote feature for example does not do that by default).
 - Make sure the assets are compiled with `SHAKAPACKER_ASSET_HOST=''` ENV variable to avoid hardcording URLs in packs output.
 
@@ -131,41 +132,41 @@ The function will return the same object with less risk:
 
 ```js
 // before
-const { globalMutableWebpackConfig, merge } = require('shakapacker');
+const { globalMutableWebpackConfig, merge } = require("shakapacker")
 
 const customConfig = {
   module: {
     rules: [
       {
-        test: require.resolve('jquery'),
-        loader: 'expose-loader',
-        options: { exposes: ['$', 'jQuery'] }
+        test: require.resolve("jquery"),
+        loader: "expose-loader",
+        options: { exposes: ["$", "jQuery"] }
       }
     ]
   }
-};
+}
 
-module.exports = merge(globalMutableWebpackConfig, customConfig);
+module.exports = merge(globalMutableWebpackConfig, customConfig)
 ```
 
 ```js
 // after
-const { generateWebpackConfig, merge } = require('shakapacker');
+const { generateWebpackConfig, merge } = require("shakapacker")
 
 const customConfig = {
   module: {
     rules: [
       {
-        test: require.resolve('jquery'),
-        loader: 'expose-loader',
-        options: { exposes: ['$', 'jQuery'] }
+        test: require.resolve("jquery"),
+        loader: "expose-loader",
+        options: { exposes: ["$", "jQuery"] }
       }
     ]
   }
-};
+}
 
 // you can also pass your config directly to the generator function to have it merged in!
-module.exports = merge(generateWebpackConfig(), customConfig);
+module.exports = merge(generateWebpackConfig(), customConfig)
 ```
 
 ## `additional_paths` are now stripped just like with `source_path`

data/docs/v9_upgrade.md

@@ -2,6 +2,8 @@
 
 This guide outlines new features, breaking changes, and migration steps for upgrading from Shakapacker v8 to v9.
 
+**📖 For detailed configuration options, see the [Configuration Guide](./configuration.md)**
+
 > **⚠️ 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
@@ -130,7 +132,6 @@ import * as styles from './Component.module.css';
 **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

data/eslint.config.fast.js

@@ -0,0 +1,134 @@
+// Fast ESLint config for quick development feedback
+// Skips type-aware rules that require TypeScript compilation
+
+const { FlatCompat } = require("@eslint/eslintrc")
+const js = require("@eslint/js")
+const typescriptParser = require("@typescript-eslint/parser")
+const typescriptPlugin = require("@typescript-eslint/eslint-plugin")
+const jestPlugin = require("eslint-plugin-jest")
+const prettierConfig = require("eslint-config-prettier")
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended
+})
+
+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)
+    ]
+  },
+
+  // Base config for all JS files
+  ...compat.extends("airbnb"),
+  {
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: "module",
+      globals: {
+        // Browser globals
+        window: "readonly",
+        document: "readonly",
+        navigator: "readonly",
+        console: "readonly",
+        // Node globals
+        process: "readonly",
+        __dirname: "readonly",
+        __filename: "readonly",
+        module: "readonly",
+        require: "readonly",
+        exports: "readonly",
+        global: "readonly",
+        Buffer: "readonly"
+      }
+    },
+    rules: {
+      // Webpack handles module resolution, not ESLint
+      "import/no-unresolved": "off",
+      // Allow importing devDependencies in config/test files
+      "import/no-extraneous-dependencies": "off",
+      // TypeScript handles extensions, not needed for JS imports
+      "import/extensions": "off",
+      indent: ["error", 2]
+    },
+    settings: {
+      react: {
+        // Suppress "react package not installed" warning
+        // This project doesn't use React but airbnb config requires react-plugin
+        version: "999.999.999"
+      }
+    }
+  },
+
+  // Jest test files
+  {
+    files: ["test/**"],
+    plugins: {
+      jest: jestPlugin
+    },
+    languageOptions: {
+      globals: {
+        ...jestPlugin.environments.globals.globals
+      }
+    },
+    rules: {
+      ...jestPlugin.configs.recommended.rules,
+      ...jestPlugin.configs.style.rules,
+      "global-require": "off",
+      "jest/prefer-called-with": "error",
+      "jest/no-conditional-in-test": "error",
+      "jest/no-test-return-statement": "error",
+      "jest/prefer-expect-resolves": "error",
+      "jest/require-to-throw-message": "error",
+      "jest/require-top-level-describe": "error",
+      "jest/prefer-hooks-on-top": "error",
+      "jest/prefer-lowercase-title": [
+        "error",
+        { ignoreTopLevelDescribe: true }
+      ],
+      "jest/prefer-spy-on": "error",
+      "jest/prefer-strict-equal": "error",
+      "jest/prefer-todo": "error"
+    }
+  },
+
+  // TypeScript files - fast mode without type-aware linting
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: {
+        // No project specified - disables type-aware linting
+        ecmaVersion: 2020,
+        sourceType: "module"
+      }
+    },
+    plugins: {
+      "@typescript-eslint": typescriptPlugin
+    },
+    rules: {
+      ...typescriptPlugin.configs.recommended.rules,
+      // Same rules as main config minus type-aware ones
+      "import/no-unresolved": "off",
+      "import/no-extraneous-dependencies": "off",
+      "import/extensions": "off",
+      "no-use-before-define": "off",
+      "@typescript-eslint/no-use-before-define": ["error"],
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_" }
+      ],
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/explicit-module-boundary-types": "off"
+    }
+  },
+
+  // Prettier config must be last to override other configs
+  prettierConfig
+]

data/eslint.config.js

@@ -0,0 +1,140 @@
+const { FlatCompat } = require("@eslint/eslintrc")
+const js = require("@eslint/js")
+const typescriptParser = require("@typescript-eslint/parser")
+const typescriptPlugin = require("@typescript-eslint/eslint-plugin")
+const jestPlugin = require("eslint-plugin-jest")
+const prettierConfig = require("eslint-config-prettier")
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended
+})
+
+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)
+    ]
+  },
+
+  // Base config for all JS files
+  ...compat.extends("airbnb"),
+  {
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: "module",
+      globals: {
+        // Browser globals
+        window: "readonly",
+        document: "readonly",
+        navigator: "readonly",
+        console: "readonly",
+        // Node globals
+        process: "readonly",
+        __dirname: "readonly",
+        __filename: "readonly",
+        module: "readonly",
+        require: "readonly",
+        exports: "readonly",
+        global: "readonly",
+        Buffer: "readonly"
+      }
+    },
+    rules: {
+      // Webpack handles module resolution, not ESLint
+      "import/no-unresolved": "off",
+      // Allow importing devDependencies in config/test files
+      "import/no-extraneous-dependencies": "off",
+      // TypeScript handles extensions, not needed for JS imports
+      "import/extensions": "off",
+      indent: ["error", 2]
+    },
+    settings: {
+      react: {
+        // Suppress "react package not installed" warning
+        // This project doesn't use React but airbnb config requires react-plugin
+        version: "999.999.999"
+      }
+    }
+  },
+
+  // Jest test files
+  {
+    files: ["test/**"],
+    plugins: {
+      jest: jestPlugin
+    },
+    languageOptions: {
+      globals: {
+        ...jestPlugin.environments.globals.globals
+      }
+    },
+    rules: {
+      ...jestPlugin.configs.recommended.rules,
+      ...jestPlugin.configs.style.rules,
+      "global-require": "off",
+      "jest/prefer-called-with": "error",
+      "jest/no-conditional-in-test": "error",
+      "jest/no-test-return-statement": "error",
+      "jest/prefer-expect-resolves": "error",
+      "jest/require-to-throw-message": "error",
+      "jest/require-top-level-describe": "error",
+      "jest/prefer-hooks-on-top": "error",
+      "jest/prefer-lowercase-title": [
+        "error",
+        { ignoreTopLevelDescribe: true }
+      ],
+      "jest/prefer-spy-on": "error",
+      "jest/prefer-strict-equal": "error",
+      "jest/prefer-todo": "error"
+    }
+  },
+
+  // TypeScript files
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: {
+        // Enables type-aware linting for better type safety
+        // Note: This can slow down linting on large codebases
+        // Consider using --cache flag with ESLint if performance degrades
+        project: "./tsconfig.eslint.json",
+        tsconfigRootDir: __dirname
+      }
+    },
+    plugins: {
+      "@typescript-eslint": typescriptPlugin
+    },
+    rules: {
+      ...typescriptPlugin.configs.recommended.rules,
+      ...typescriptPlugin.configs["recommended-requiring-type-checking"].rules,
+      // TypeScript compiler handles module resolution
+      "import/no-unresolved": "off",
+      // Allow importing devDependencies in TypeScript files
+      "import/no-extraneous-dependencies": "off",
+      // TypeScript handles file extensions via moduleResolution
+      "import/extensions": "off",
+      // Disable base rule in favor of TypeScript version
+      "no-use-before-define": "off",
+      "@typescript-eslint/no-use-before-define": ["error"],
+      // Allow unused vars if they start with underscore (convention for ignored params)
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_" }
+      ],
+      // 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"
+    }
+  },
+
+  // Prettier config must be last to override other configs
+  prettierConfig
+]

data/knip.ts

@@ -0,0 +1,54 @@
+import type { KnipConfig } from "knip"
+
+const config: KnipConfig = {
+  project: ["package/**/*.{ts,js}", "test/**/*.{ts,js}", "scripts/**/*.js"],
+  ignore: [
+    "package/**/*.d.ts",
+    "package/**/*.js",
+    "package/**/*.js.map",
+    "package/**/*.d.ts.map",
+    "test/fixtures/**",
+    "test/helpers.js", // Test utility file used by jest
+    "spec/**",
+    "gemfiles/**"
+  ],
+  ignoreBinaries: ["sed"],
+  ignoreDependencies: [
+    // These are peer dependencies that may not be directly imported
+    "@babel/core",
+    "@types/babel__core",
+    "@types/webpack",
+    "webpack-dev-server",
+    // Test/build tooling
+    "memory-fs",
+    "thenify",
+    // Used in type tests but not directly imported
+    "@rspack/plugin-react-refresh",
+    // CLI tools used by developers
+    "@rspack/cli",
+    "webpack-cli",
+    "husky",
+    // Optional dependencies used in webpack/rspack configs
+    "mini-css-extract-plugin",
+    "webpack-assets-manifest",
+    "webpack-subresource-integrity",
+    "rspack-manifest-plugin",
+    "sass-loader",
+    // Package merger utility
+    "@types/webpack-merge",
+    // Optional runtime dependencies
+    "ts-node",
+    "@pmmmwh/react-refresh-webpack-plugin",
+    // Optional peer dependencies referenced in code
+    "@rspack/core",
+    "@swc/core",
+    "babel-loader",
+    "compression-webpack-plugin",
+    "css-loader",
+    "esbuild-loader",
+    "swc-loader",
+    "webpack"
+  ]
+}
+
+export default config

data/lib/install/bin/export-bundler-config

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+// Minimal shim - all logic is in the TypeScript module
+const { run } = require("shakapacker/configExporter")
+
+run(process.argv.slice(2))
+  .then((exitCode) => process.exit(exitCode))
+  .catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })

data/lib/install/bin/shakapacker

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ENV["RAILS_ENV"] ||= "development"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 ENV["APP_ROOT"] ||= File.expand_path("..", __dir__)
 
 require "bundler/setup"

data/lib/install/bin/shakapacker-dev-server

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 ENV["RAILS_ENV"] ||= "development"
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile", __FILE__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 
 require "bundler/setup"
 require "shakapacker"

data/lib/install/config/shakapacker.yml

@@ -43,11 +43,22 @@ default: &default
   # 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'
+  javascript_transpiler: "swc"
 
   # Select assets bundler to use
   # Available options: 'webpack' (default) or 'rspack'
-  assets_bundler: 'webpack'
+  assets_bundler: "webpack"
+
+  # Path to the directory containing webpack/rspack config files
+  # Defaults to 'config/webpack' for webpack or 'config/rspack' for rspack
+  # Use '.' to specify the root directory of your project
+  # assets_bundler_config_path: config/webpack
+
+  # Hook to run before webpack compilation (e.g., for generating dynamic entry points)
+  # SECURITY: Only reference trusted scripts within your project. The hook command will be
+  # validated to ensure it points to a file within the project root.
+  # Example: precompile_hook: 'bin/shakapacker-precompile-hook'
+  # precompile_hook: ~
 
   # Raises an error if there is a mismatch in the shakapacker gem and npm package being used
   ensure_consistent_versioning: true
@@ -112,14 +123,14 @@ development:
     # Should we use gzip compression?
     compress: true
     # Note that apps that do not check the host are vulnerable to DNS rebinding attacks
-    allowed_hosts: 'auto'
+    allowed_hosts: "auto"
     # Shows progress and colorizes output of bin/shakapacker[-dev-server]
     pretty: true
     headers:
-      'Access-Control-Allow-Origin': '*'
+      "Access-Control-Allow-Origin": "*"
     static:
       watch:
-        ignored: '**/node_modules/**'
+        ignored: "**/node_modules/**"
 
 test:
   <<: *default

data/lib/shakapacker/bundler_switcher.rb

@@ -241,6 +241,13 @@ module Shakapacker
             raise "Failed to install prod dependencies"
           end
         end
+
+        # Run a full install to ensure optional dependencies (like native bindings) are properly resolved
+        # This is especially important for packages like @rspack/core that use platform-specific native modules
+        unless package_json.manager.install
+          puts "❌ Failed to run full install to resolve optional dependencies"
+          raise "Failed to run full install"
+        end
       end
 
       def get_package_json

data/lib/shakapacker/compiler.rb

@@ -1,5 +1,6 @@
 require "open3"
 require "fileutils"
+require "shellwords"
 
 require_relative "compiler_strategy"
 
@@ -26,6 +27,7 @@ class Shakapacker::Compiler
       true
     else
       acquire_ipc_lock do
+        run_precompile_hook if config.precompile_hook
         run_webpack.tap do |success|
           after_compile_hook
         end
@@ -78,6 +80,84 @@ class Shakapacker::Compiler
       /ruby/.match?(first_line) ? RbConfig.ruby : ""
     end
 
+    def run_precompile_hook
+      hook_command = config.precompile_hook
+      hook_spec = validate_precompile_hook(hook_command)
+
+      logger.info "Running precompile hook: #{hook_command}"
+
+      runtime_env = webpack_env.merge(hook_spec[:env])
+      stdout, stderr, status = Open3.capture3(
+        runtime_env,
+        hook_spec[:executable],
+        *hook_spec[:args],
+        chdir: File.expand_path(config.root_path)
+      )
+
+      if status.success?
+        logger.info "Precompile hook completed successfully"
+        logger.info stdout unless stdout.empty?
+        logger.warn stderr unless stderr.empty?
+      else
+        non_empty_streams = [stdout, stderr].delete_if(&:empty?)
+        logger.error "\nPRECOMPILE HOOK FAILED:\nEXIT STATUS: #{status.exitstatus}\nCOMMAND: #{hook_command}\nOUTPUTS:\n#{non_empty_streams.join("\n\n")}"
+        logger.error "\nTo fix this:"
+        logger.error "  1. Check that the hook script exists and is executable"
+        logger.error "  2. Test the hook command manually: #{hook_command}"
+        logger.error "  3. Review the error output above for details"
+        logger.error "  4. You can disable the hook temporarily by commenting out 'precompile_hook' in shakapacker.yml"
+        raise "Precompile hook '#{hook_command}' failed with exit status #{status.exitstatus}"
+      end
+    end
+
+    def validate_precompile_hook(hook_command)
+      hook_tokens = begin
+        Shellwords.shellsplit(hook_command)
+      rescue ArgumentError => e
+        raise "Shakapacker configuration error: Invalid precompile_hook command syntax: #{e.message}. Check for unmatched quotes in: #{hook_command}"
+      end
+
+      env_assignments = {}
+      while hook_tokens.first&.match?(/\A[A-Za-z_][A-Za-z0-9_]*=/)
+        key, value = hook_tokens.shift.split("=", 2)
+        env_assignments[key] = value
+      end
+
+      executable = hook_tokens.shift
+      if executable.nil? || executable.empty?
+        raise "Shakapacker configuration error: precompile_hook must include an executable command. Got: #{hook_command}"
+      end
+
+      executable_path = config.root_path.join(executable)
+
+      # Security: Resolve symlinks and verify the hook points to a file within the project
+      # This prevents symlink bypass attacks and path traversal attacks
+      begin
+        resolved_path = executable_path.realpath
+        resolved_root = config.root_path.realpath
+      rescue Errno::ENOENT
+        # If file doesn't exist, use cleanpath for basic validation
+        resolved_path = executable_path.cleanpath
+        resolved_root = config.root_path.cleanpath
+      end
+
+      # Verify path is within project root with proper separator check
+      # Using File::SEPARATOR prevents partial path matches (e.g., /project vs /project-evil)
+      unless resolved_path.to_s.start_with?(resolved_root.to_s + File::SEPARATOR)
+        raise "Security Error: precompile_hook must reference a script within the project root. " \
+              "Got: #{hook_command} (resolved to: #{resolved_path})"
+      end
+
+      # Warn if the executable doesn't exist within the project
+      unless File.exist?(executable_path)
+        logger.warn "⚠️  Warning: precompile_hook executable not found: #{executable_path}"
+        logger.warn "   The hook command is configured but the script does not exist within the project root."
+        logger.warn "   Please ensure the script exists or remove 'precompile_hook' from your shakapacker.yml configuration."
+      end
+
+      { env: env_assignments, executable: executable, args: hook_tokens }
+    end
+
     def run_webpack
       logger.info "Compiling..."