shakapacker 9.0.0.beta.7 → 9.0.0.beta.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca5207ce21d40303f0a0250d140763ca93000a318ba28a9ac8efff358ce59310
-  data.tar.gz: f494c9a43b2c9fc704ca6dc1e3110f0c7048759a13e3f8254c44735e91a58da0
+  metadata.gz: 6b968c57e16cafe6ddb6fb317b442db6b96682ee075498f3b8bc60f43f87d7bd
+  data.tar.gz: a3bf4f39a4c6b869e3301723423387577a78a0818403c1bb31efd42f9bc0ac7c
 SHA512:
-  metadata.gz: a13fd3b73ffb91546e25c8226731efd4cdf6e8024893011795e32f379d2c3ffd14a4b5286b2a32499447405a01624b50805aafd6749112538e560ab21bc58e7e
-  data.tar.gz: d9911ec4c3a53a6baf3598e48b29e74684113a6514e979c73b69479905399e94abc67c0792a51c1cf12c5961a771c9de1f19e1800991f9a638dfab5ebcd1e606
+  metadata.gz: ebfa33ceea921c0c66f9a9affb4eb1c736c981696d87523e4a55f82311e6779a28b3b9ca0b8b8a270fb00dbd04302be57928091f4b7c7b580ee66d2585c98f4f
+  data.tar.gz: 61a683b023eec46e7beb3a294db371b28ac1d8668744d7212ab938eb5a0a1fe53dba7763f5f9e90374ed329cb2f6ae07a232f3b0970e3bb4d504f4b79ea9eaeb

data/.eslintrc.fast.js

@@ -0,0 +1,40 @@
+// Fast ESLint config for quick development feedback
+// Skips type-aware rules that require TypeScript compilation
+
+const baseConfig = require("./.eslintrc.js")
+
+module.exports = {
+  ...baseConfig,
+  overrides: [
+    ...baseConfig.overrides.filter((o) => !o.files.includes("**/*.{ts,tsx}")),
+    {
+      files: ["**/*.{ts,tsx}"],
+      parser: "@typescript-eslint/parser",
+      parserOptions: {
+        // No project specified - disables type-aware linting
+        ecmaVersion: 2020,
+        sourceType: "module"
+      },
+      extends: [
+        "plugin:@typescript-eslint/recommended",
+        // Skip the "recommended-requiring-type-checking" preset
+        "plugin:prettier/recommended"
+      ],
+      plugins: ["@typescript-eslint"],
+      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"
+      }
+    }
+  ]
+}

data/.eslintrc.js

@@ -1,11 +1,22 @@
 module.exports = {
+  root: true, // Prevent ESLint from looking in parent directories
   extends: ["airbnb", "plugin:prettier/recommended"],
   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"
+    }
+  },
   env: {
     browser: true,
     node: true
@@ -31,6 +42,43 @@ module.exports = {
         "jest/prefer-strict-equal": "error",
         "jest/prefer-todo": "error"
       }
+    },
+    {
+      files: ["**/*.{ts,tsx}"],
+      parser: "@typescript-eslint/parser",
+      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
+      },
+      extends: [
+        "plugin:@typescript-eslint/recommended",
+        "plugin:@typescript-eslint/recommended-requiring-type-checking",
+        "plugin:prettier/recommended"
+      ],
+      plugins: ["@typescript-eslint"],
+      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"
+      }
     }
   ]
 }

data/.gitignore

@@ -11,6 +11,7 @@ yarn-error.log*
 /log
 gemfiles/*.lock
 .DS_Store
+.eslintcache
 
 .yalc
 yalc.lock
@@ -25,11 +26,8 @@ package/**/*.js
 !package/index.d.ts
 !package/loaders.d.ts
 !package/webpack-types.d.ts
-!package/babel/preset.js
 !package/babel/preset-react.js
-!package/rules/*.js
 !package/loaders/*.js
-!package/plugins/*.js
 !package/__mocks__/*.js
 !package/utils/get_style_rule.js
 !package/utils/node_modules.js

data/.npmignore

@@ -10,6 +10,7 @@
 /gemfiles
 /.github
 /.circleci
+/.husky
 /.byebug_history
 .DS_Store
 yarn-debug.log*

data/CHANGELOG.md

@@ -9,7 +9,70 @@
 ## [Unreleased]
 Changes since the last non-beta release.
 
-## [v9.0.0-beta.4] - Unreleased
+### Added
+- **Phase 5 TypeScript Migration - Framework-Specific Modules** by [justin808](https://github.com/justin808)
+  - Converted framework-specific modules to TypeScript
+  - Migrated package/rspack/index.js to TypeScript
+  - Migrated package/swc/index.js to TypeScript
+  - Migrated package/esbuild/index.js to TypeScript
+  - Migrated package/babel/preset.js to TypeScript
+  - Added @types/babel__core for enhanced type safety
+  - All 130 tests passing
+- **Phase 6 TypeScript Migration - Final Cleanup** (by [justin808](https://github.com/justin808))
+  - Added TypeScript ESLint support with @typescript-eslint/parser and @typescript-eslint/eslint-plugin
+  - Configured TypeScript-specific linting rules for improved code quality
+  - Verified strict mode is enabled in TypeScript configuration
+  - Enhanced developer experience with TypeScript linting across the entire codebase
+
+## [v9.0.0-beta.7] - October 1, 2025
+
+### Added
+- **Phase 2 TypeScript Migration - Core Modules** ([PR 608](https://github.com/shakacode/shakapacker/pull/608) by [justin808](https://github.com/justin808))
+  - Converted core modules to TypeScript: config.ts, env.ts, and utilities
+  - Enhanced type safety across the codebase
+  - Better IDE support and autocomplete
+- **Phase 3 TypeScript Migration - Environment Files** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
+  - Converted all environment configuration files to TypeScript (development, production, test)
+  - Added centralized type exports for consumer use (import from "shakapacker/types")
+  - Created shared TypeScript interfaces for environment configurations
+  - Introduced structured error codes for programmatic error handling
+  - Exported shared types: WebpackConfig, RspackConfig, EnvironmentConfig
+- **Optional Peer Dependencies** ([PR 615](https://github.com/shakacode/shakapacker/pull/615) by [justin808](https://github.com/justin808))
+  - Restored peer dependencies as optional to improve package version tracking
+  - Added peerDependenciesMeta marking all peers as optional
+  - Moved webpack-merge to direct dependencies (required at runtime)
+  - Prevents installation warnings while maintaining upgrade visibility
+- **Migration Tooling Improvements** ([PR 613](https://github.com/shakacode/shakapacker/pull/613) by [justin808](https://github.com/justin808))
+  - Added SWC migration helper: rake shakapacker:migrate:to_swc
+  - Enhanced error messages for missing dependencies
+  - Improved doctor command output
+
+### Security
+- **Path Validation Utilities** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
+  - Added validation to prevent directory traversal attacks
+  - Implemented environment variable sanitization to prevent injection
+  - Enforced strict port validation (reject strings with non-digits)
+  - Added SHAKAPACKER_NPM_PACKAGE path validation (only .tgz/.tar.gz allowed)
+  - Path traversal security checks now run regardless of validation mode
+
+### Changed
+- **Build Process Improvements** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
+  - Environment JS files now generated during npm publish (not committed to git)
+  - Prevents TypeScript source and compiled JS from getting out of sync
+  - Auto-format compiled JavaScript during build process
+  - Enhanced .npmignore to exclude TypeScript sources, include compiled JS
+
+### Performance
+- **Validation Caching** ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
+  - Implemented TTL-based validation caching (5s watch, 1min dev, infinite prod)
+  - Made cache TTL configurable via SHAKAPACKER_CACHE_TTL environment variable
+  - Lazy-loaded and cached watch mode detection
+
+### Fixed
+- Fixed clearValidationCache() to actually clear the cache ([PR 614](https://github.com/shakacode/shakapacker/pull/614) by [justin808](https://github.com/justin808))
+- Fixed private_output_path configuration edge cases ([PR 604](https://github.com/shakacode/shakapacker/pull/604) by [justin808](https://github.com/justin808))
+
+## [v9.0.0-beta.4] - September 15, 2025
 
 ### ⚠️ Breaking Changes
 

data/CONTRIBUTING.md

@@ -3,6 +3,7 @@
 Thank you for your interest in contributing to Shakapacker! We welcome all contributions that align with our project goals and values. To ensure a smooth and productive collaboration, please follow these guidelines.
 
 ## Contents
+
 - [Reporting Issues](#reporting-issues)
 - [Submitting Pull Requests](#submitting-pull-requests)
 - [Setting Up a Development Environment](#setting-up-a-development-environment)
@@ -10,44 +11,89 @@ Thank you for your interest in contributing to Shakapacker! We welcome all contr
 - [Testing the generator](#testing-the-generator)
 
 ## Reporting Issues
+
 If you encounter any issues with the project, please first check the existing issues (including closed ones). If the issues is not reported before, please opening an issue on our GitHub repository. Please provide a clear and detailed description of the issue, including steps to reproduce it. Creating a demo repository to demonstrate the issue would be ideal (and in some cases necessary).
 
 If looking to contribute to the project by fixing existing issues, we recommend looking at issues, particularly with the "[help wanted](https://github.com/shakacode/shakapacker/issues?q=is%3Aissue+label%3A%22help+wanted%22)" label.
 
 ## Submitting Pull Requests
+
 We welcome pull requests that fix bugs, add new features, or improve existing ones. Before submitting a pull request, please make sure to:
 
-  - Open an issue about what you want to propose before start working on.
-  - Fork the repository and create a new branch for your changes.
-  - Write clear and concise commit messages.
-  - Follow our code style guidelines.
-  - Write tests for your changes and [make sure all tests pass](#making-sure-your-changes-pass-all-tests).
-  - Update the documentation as needed.
-  - Update CHANGELOG.md if the changes affect public behavior of the project.
+- Open an issue about what you want to propose before start working on.
+- Fork the repository and create a new branch for your changes.
+- Write clear and concise commit messages.
+- Follow our code style guidelines.
+- Write tests for your changes and [make sure all tests pass](#making-sure-your-changes-pass-all-tests).
+- Update the documentation as needed.
+- Update CHANGELOG.md if the changes affect public behavior of the project.
 
 ---
+
+## Git Hooks (Optional)
+
+This project includes configuration for git hooks via `husky` and `lint-staged`, but they are **opt-in for contributors**.
+
+**Why are hooks optional?** As a library project, we don't enforce git hooks because:
+
+- Different contributors may have different workflows
+- Forcing hooks can interfere with contributor tooling
+- CI/CD handles the final validation
+
+To enable pre-commit hooks locally:
+
+```bash
+npx husky install
+npx husky add .husky/pre-commit "npx lint-staged"
+```
+
+---
+
+## Linting and Code Quality
+
+### Running Linters
+
+```bash
+# Full linting with type checking (slower but thorough)
+yarn lint
+
+# Fast linting without type checking (for quick feedback)
+yarn lint:fast
+
+# With caching for better performance
+yarn lint --cache
+```
+
+**Performance Note:** TypeScript ESLint uses type-aware linting for better type safety, which can be slower on large codebases. Use `yarn lint:fast` during development for quick feedback.
+
+---
+
 ## Setting Up a Development Environment
 
 1. Install [Yarn](https://classic.yarnpkg.com/)
 2. To test your changes on a Rails test project do the following steps:
+
    - For Ruby gem, update `Gemfile` and point the `shakapacker` to the locally developing Shakapacker project:
-      ```ruby
-      gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
-      ```
+     ```ruby
+     gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
+     ```
    - For npm package, use `yalc` with following steps:
-      ```bash
-      # In Shakapacker root directory
-      yalc publish
-      # In Rails app for testing
-      yalc link shakapacker
-
-      # After every change in shakapacker, run the following in Shakapacker directory
-      yalc push # or yalc publish --push
-      ```
+
+     ```bash
+     # In Shakapacker root directory
+     yalc publish
+     # In Rails app for testing
+     yalc link shakapacker
+
+     # After every change in shakapacker, run the following in Shakapacker directory
+     yalc push # or yalc publish --push
+     ```
+
 3. Run the following commands to set up the development environment.
    ```
    bundle install
    yarn install
+   yarn prepare:husky  # Set up pre-commit hooks for linting
    ```
 
 ## Understanding Optional Peer Dependencies
@@ -59,11 +105,13 @@ Shakapacker uses optional peer dependencies (via `peerDependenciesMeta`) for max
 - **Version constraints still apply** - When a package is installed, version compatibility is enforced
 
 ### When modifying dependencies:
+
 1. Add new peer dependencies to both `peerDependencies` and `peerDependenciesMeta` (marking as optional)
 2. Keep version ranges synchronized between `devDependencies` and `peerDependencies`
 3. Test with multiple package managers: `npm`, `yarn`, and `pnpm`
 
 ### Testing peer dependency changes:
+
 ```bash
 # Test with npm (no warnings expected)
 cd /tmp && mkdir test-npm && cd test-npm
@@ -129,6 +177,7 @@ bundle exec rake run_spec:gem
 ```
 
 #### 4.4 Run only Shakapacker gem specs for backward compatibility
+
 These specs are to check Shakapacker v7 backward compatibility with v6.x
 
 ```
@@ -136,6 +185,7 @@ bundle exec rake run_spec:gem_bc
 ```
 
 #### 4.5 Run dummy app test
+
 For this, you need `yalc` to be installed on your local machine
 
 ```
@@ -143,6 +193,7 @@ bundle exec rake run_spec:dummy
 ```
 
 #### 4.6 Testing the installer
+
 To ensure that your installer works as expected, either you can run `bundle exec rake run_spec:install`, or take the following manual testing steps:
 
 1. Update the `Gemfile` so that gem `shakapacker` has a line like this, pointing to your developing Shakapacker:
@@ -152,7 +203,7 @@ To ensure that your installer works as expected, either you can run `bundle exec
 2. Run `bundle install` to install the updated gem.
 3. Run `bundle exec rails shakapacker:install` to confirm that you got the right changes.
 
- **Note:** Ensure that you use bundle exec otherwise the installed shakapacker gem will run and not the one you are working on.
+**Note:** Ensure that you use bundle exec otherwise the installed shakapacker gem will run and not the one you are working on.
 
 ## CI Workflows
 
@@ -161,6 +212,7 @@ Shakapacker uses GitHub Actions for continuous integration. The CI workflows use
 ### Package Manager Choice
 
 The project uses Yarn in CI workflows for the following reasons:
+
 - Deterministic dependency resolution with `yarn.lock`
 - Faster installation with offline mirror support
 - Better workspace support for monorepo-style testing
@@ -174,14 +226,16 @@ The project uses Yarn in CI workflows for the following reasons:
 - `.github/workflows/generator.yml` - Generator installation tests
 
 All workflows use:
+
 ```yaml
 - uses: actions/setup-node@v4
   with:
-    cache: 'yarn'
+    cache: "yarn"
     cache-dependency-path: spec/dummy/yarn.lock
 ```
 
 And install dependencies with:
+
 ```bash
 yarn install
 ```

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shakapacker (9.0.0.beta.7)
+    shakapacker (9.0.0.beta.8)
       activesupport (>= 5.2)
       package_json
       rack-proxy (>= 0.6.1)

data/TODO.md

@@ -22,22 +22,21 @@
 - [ ] Convert dev_server.js
 - [ ] Convert webpackDevServerConfig.js
 
-### Phase 4: Rules & Loaders
-- [ ] Convert all files in `package/rules/`
-- [ ] Convert all files in `package/plugins/`
-- [ ] Convert all files in `package/optimization/`
-
-### Phase 5: Framework-Specific Modules
-- [ ] Convert rspack support files
-- [ ] Convert swc support files
-- [ ] Convert esbuild support files
-- [ ] Convert babel preset
-
-### Phase 6: Final Cleanup
-- [ ] Convert remaining utilities
-- [ ] Add TypeScript linting
-- [ ] Enable strict mode
-- [ ] Update documentation
+### Phase 4: Rules & Loaders (PR #620) ✅
+- [x] Convert all files in `package/rules/`
+- [x] Convert all files in `package/plugins/`
+- [x] Convert all files in `package/optimization/`
+
+### Phase 5: Framework-Specific Modules ✅
+- [x] Convert rspack support files
+- [x] Convert swc support files
+- [x] Convert esbuild support files
+- [x] Convert babel preset
+
+### Phase 6: Final Cleanup ✅
+- [x] Add TypeScript linting with @typescript-eslint
+- [x] Verify strict mode is enabled (already configured)
+- [x] Update documentation
 
 ## Why Gradual Migration?
 - **Lower risk**: Each phase can be tested independently

data/lib/shakapacker/version.rb

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

data/package/babel/preset.ts

@@ -0,0 +1,56 @@
+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/esbuild/index.ts

@@ -0,0 +1,42 @@
+/* eslint global-require: 0 */
+/* eslint import/no-dynamic-require: 0 */
+
+import { resolve } from "path"
+import { existsSync } from "fs"
+import { merge } from "webpack-merge"
+import type { RuleSetRule } from "webpack"
+
+const LOADER_EXT_REGEX = /\.([jt]sx?)(\.erb)?$/
+
+const getLoaderExtension = (filename: string): string => {
+  const matchData = filename.match(LOADER_EXT_REGEX)
+
+  if (!matchData) {
+    return "js"
+  }
+
+  return matchData[1] ?? "js"
+}
+
+const getCustomConfig = (): Partial<RuleSetRule> => {
+  const path = resolve("config", "esbuild.config.js")
+  if (existsSync(path)) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(path)
+  }
+  return {}
+}
+
+const getEsbuildLoaderConfig = (filenameToProcess: string): RuleSetRule => {
+  const customConfig = getCustomConfig()
+  const defaultConfig: RuleSetRule = {
+    loader: require.resolve("esbuild-loader"),
+    options: {
+      loader: getLoaderExtension(filenameToProcess)
+    }
+  }
+
+  return merge(defaultConfig, customConfig)
+}
+
+export { getEsbuildLoaderConfig }

data/package/optimization/rspack.ts

@@ -0,0 +1,36 @@
+const { requireOrError } = require("../utils/requireOrError")
+const { error: logError } = require("../utils/debug")
+
+const rspack = requireOrError("@rspack/core")
+
+interface OptimizationConfig {
+  minimize: boolean
+  minimizer?: unknown[]
+}
+
+const getOptimization = (): OptimizationConfig => {
+  // Use Rspack's built-in minification instead of terser-webpack-plugin
+  const result: OptimizationConfig = { minimize: true }
+  try {
+    result.minimizer = [
+      new rspack.SwcJsMinimizerRspackPlugin(),
+      new rspack.LightningCssMinimizerRspackPlugin()
+    ]
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    const errorStack = error instanceof Error ? error.stack : ''
+    // Log full error with stack trace
+    logError(
+      `Failed to configure Rspack minimizers: ${errorMessage}\n${errorStack}`
+    )
+    // Re-throw the error to properly propagate it
+    throw new Error(
+      `Could not configure Rspack minimizers: ${errorMessage}. Please check that @rspack/core is properly installed.`
+    )
+  }
+  return result
+}
+
+export = {
+  getOptimization
+}

data/package/optimization/{webpack.js → webpack.ts}

@@ -3,7 +3,7 @@ const { requireOrError } = require("../utils/requireOrError")
 const TerserPlugin = requireOrError("terser-webpack-plugin")
 const { moduleExists } = require("../utils/helpers")
 
-const tryCssMinimizer = () => {
+const tryCssMinimizer = (): unknown | null => {
   if (
     moduleExists("css-loader") &&
     moduleExists("css-minimizer-webpack-plugin")
@@ -15,12 +15,20 @@ const tryCssMinimizer = () => {
   return null
 }
 
-const getOptimization = () => {
+interface OptimizationConfig {
+  minimizer: unknown[]
+}
+
+const getOptimization = (): OptimizationConfig => {
   return {
     minimizer: [
       tryCssMinimizer(),
       new TerserPlugin({
-        parallel: Number.parseInt(process.env.SHAKAPACKER_PARALLEL, 10) || true,
+        // SHAKAPACKER_PARALLEL env var: number of parallel workers, or true for auto (os.cpus().length - 1)
+        // If not set or invalid, defaults to true (automatic parallelization)
+        parallel: process.env.SHAKAPACKER_PARALLEL
+          ? Number.parseInt(process.env.SHAKAPACKER_PARALLEL, 10) || true
+          : true,
         terserOptions: {
           parse: {
             // Let terser parse ecma 8 code but always output
@@ -44,6 +52,6 @@ const getOptimization = () => {
   }
 }
 
-module.exports = {
+export = {
   getOptimization
 }