shakapacker 9.3.0.beta.4 → 9.3.0.beta.6

data/package/configExporter/cli.ts

@@ -596,6 +596,9 @@ async function runValidateCommand(options: ExportOptions): Promise<number> {
       clearBuildEnvironmentVariables()
       restoreBuildEnvironmentVariables(savedEnv)
 
+      // Clear shakapacker config cache between builds
+      shakapackerConfigCache = null
+
       // Get the build's environment to use for auto-detection
       const buildConfig = config.builds[buildName]
       const buildEnv =
@@ -692,6 +695,9 @@ async function runAllBuildsCommand(options: ExportOptions): Promise<number> {
       clearBuildEnvironmentVariables()
       restoreBuildEnvironmentVariables(savedEnv)
 
+      // Clear shakapacker config cache between builds
+      shakapackerConfigCache = null
+
       // Create a modified options object for this build
       const buildOptions = { ...resolvedOptions, build: buildName }
       const configs = await loadConfigsForEnv(undefined, buildOptions, appRoot)
@@ -770,6 +776,9 @@ async function runDoctorMode(
           clearBuildEnvironmentVariables()
           restoreBuildEnvironmentVariables(savedEnv)
 
+          // Clear shakapacker config cache between builds
+          shakapackerConfigCache = null
+
           const configs = await loadConfigsForEnv(
             undefined,
             { ...options, build: buildName },
@@ -798,9 +807,13 @@ async function runDoctorMode(
         // If config file exists but is invalid, show error and exit
         const errorMessage =
           error instanceof Error ? error.message : String(error)
-        console.error(`\n❌ Config file found but invalid: ${errorMessage}`)
+        console.error(`\n❌ Error loading build configuration:`)
+        console.error(`\n${errorMessage}`)
+        console.error(
+          `\n💡 To fix this issue, check your build config in ${configFilePath}`
+        )
         console.error(
-          `Fix the config file or run: bin/shakapacker-config --init\n`
+          `   or run: bin/shakapacker-config --init to regenerate it.\n`
         )
         throw error
       }
@@ -825,6 +838,9 @@ async function runDoctorMode(
       clearBuildEnvironmentVariables()
       restoreBuildEnvironmentVariables(savedEnv)
 
+      // Clear shakapacker config cache between builds
+      shakapackerConfigCache = null
+
       // Set WEBPACK_SERVE for HMR config
       if (hmr) {
         process.env.WEBPACK_SERVE = "true"
@@ -1039,6 +1055,12 @@ async function loadConfigsForEnv(
       "DYLD_INSERT_LIBRARIES"
     ]
 
+    if (process.env.VERBOSE) {
+      console.log(
+        `[Config Exporter] Setting environment variables from build config...`
+      )
+    }
+
     for (const [key, value] of Object.entries(resolvedBuild.environment)) {
       if (DANGEROUS_ENV_VARS.includes(key)) {
         console.warn(
@@ -1053,6 +1075,9 @@ async function loadConfigsForEnv(
         )
         continue
       }
+      if (process.env.VERBOSE) {
+        console.log(`[Config Exporter]   ${key}=${value}`)
+      }
       process.env[key] = value
     }
 
@@ -1080,6 +1105,21 @@ async function loadConfigsForEnv(
     const railsEnv =
       options.env || resolvedBuild.environment.RAILS_ENV || finalEnv
     process.env.RAILS_ENV = railsEnv
+
+    // Auto-set CLIENT_BUNDLE_ONLY/SERVER_BUNDLE_ONLY from outputs if not already in environment
+    // This allows webpack configs to return the correct number of bundles
+    if (
+      !resolvedBuild.environment.CLIENT_BUNDLE_ONLY &&
+      !resolvedBuild.environment.SERVER_BUNDLE_ONLY
+    ) {
+      if (buildOutputs.length === 1) {
+        if (buildOutputs[0] === "client") {
+          process.env.CLIENT_BUNDLE_ONLY = "yes"
+        } else if (buildOutputs[0] === "server") {
+          process.env.SERVER_BUNDLE_ONLY = "yes"
+        }
+      }
+    }
   } else {
     // No build config - use CLI env or default
     finalEnv = env || "development"
@@ -1092,6 +1132,7 @@ async function loadConfigsForEnv(
     process.env.RAILS_ENV = finalEnv
   }
 
+  // Handle CLI flags for client/server only
   if (options.clientOnly) {
     process.env.CLIENT_BUNDLE_ONLY = "yes"
   } else if (options.serverOnly) {
@@ -1165,7 +1206,19 @@ async function loadConfigsForEnv(
   })
 
   // eslint-disable-next-line @typescript-eslint/no-var-requires
-  let loadedConfig = require(configFile)
+  let loadedConfig: any
+  try {
+    loadedConfig = require(configFile)
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    throw new Error(
+      `Failed to load webpack/rspack config file.\n\n` +
+        `Config file: ${configFile}\n` +
+        `Build: ${buildName || "default"}\n` +
+        `Error: ${errorMessage}\n\n` +
+        `Tip: Check that the config file is valid and doesn't have syntax errors.`
+    )
+  }
 
   // Handle ES module default export
   if (typeof loadedConfig === "object" && "default" in loadedConfig) {
@@ -1198,10 +1251,41 @@ async function loadConfigsForEnv(
     } catch (error: unknown) {
       const errorMessage =
         error instanceof Error ? error.message : String(error)
+
+      // Build detailed environment information for debugging
+      const envDetails = [
+        `Config file: ${configFile}`,
+        `Build: ${buildName || "default"}`,
+        ``,
+        `Current Environment Variables:`,
+        `  NODE_ENV: ${process.env.NODE_ENV || "(not set)"}`,
+        `  RAILS_ENV: ${process.env.RAILS_ENV || "(not set)"}`,
+        `  CLIENT_BUNDLE_ONLY: ${process.env.CLIENT_BUNDLE_ONLY || "(not set)"}`,
+        `  SERVER_BUNDLE_ONLY: ${process.env.SERVER_BUNDLE_ONLY || "(not set)"}`,
+        `  WEBPACK_SERVE: ${process.env.WEBPACK_SERVE || "(not set)"}`,
+        ``,
+        `Bundler env args: ${JSON.stringify(envObject)}`,
+        `Mode: ${finalEnv}`,
+        ``,
+        `Error: ${errorMessage}`,
+        ``
+      ]
+
+      // Add suggestion based on common error patterns
+      let suggestion = `Check your webpack/rspack config for errors. The config function threw an exception when called.`
+      if (errorMessage.includes("NODE_ENV") && !process.env.NODE_ENV) {
+        suggestion =
+          `NODE_ENV is not set. ` +
+          `Your build config should set NODE_ENV in the 'environment' section.\n` +
+          `Example:\n` +
+          `  environment:\n` +
+          `    NODE_ENV: "development"`
+      }
+
       throw new Error(
         `Failed to execute config function: ${errorMessage}\n` +
-          `Config file: ${configFile}\n` +
-          `Environment: ${JSON.stringify(envObject)}`
+          envDetails.join("\n") +
+          `\nTip: ${suggestion}`
       )
     }
   }
@@ -1212,29 +1296,81 @@ async function loadConfigsForEnv(
     : [loadedConfig]
   const results: Array<{ config: any; metadata: ConfigMetadata }> = []
 
+  // Validate config count matches expected outputs
+  if (buildOutputs.length > 0 && configs.length !== buildOutputs.length) {
+    const errorLines = [
+      `Webpack config returned ${configs.length} config(s) but outputs array specifies ${buildOutputs.length}.`,
+      ``,
+      `Build: ${buildName || "default"}`,
+      `Config file: ${configFile}`,
+      `Expected outputs: [${buildOutputs.join(", ")}]`,
+      `Actual configs returned: ${configs.length}`,
+      ``,
+      `This mismatch means:`
+    ]
+
+    if (configs.length < buildOutputs.length) {
+      errorLines.push(
+        `  - Your webpack config is returning FEWER configs than expected.`,
+        `  - Either update your webpack config to return ${buildOutputs.length} config(s),`,
+        `  - Or update the 'outputs' array in your build config to match what webpack returns.`
+      )
+    } else {
+      errorLines.push(
+        `  - Your webpack config is returning MORE configs than expected.`,
+        `  - Either update the 'outputs' array to include all ${configs.length} outputs,`,
+        `  - Or update your webpack config to return only ${buildOutputs.length} config(s).`
+      )
+    }
+
+    errorLines.push(
+      ``,
+      `Example fix in build config:`,
+      `  outputs:`,
+      ...Array.from({ length: configs.length }, (_, i) =>
+        i < buildOutputs.length
+          ? `    - ${buildOutputs[i]}`
+          : `    - config-${i + 1}  # Add a name for this config`
+      )
+    )
+
+    throw new Error(errorLines.join("\n"))
+  }
+
+  // Debug logging
+  if (process.env.VERBOSE || buildOutputs.length > 0) {
+    console.log(
+      `[Config Exporter] Webpack returned ${configs.length} config(s), buildOutputs: [${buildOutputs.join(", ")}]`
+    )
+    if (buildOutputs.length > 0 && configs.length === buildOutputs.length) {
+      console.log(
+        `[Config Exporter] ✓ Config count matches outputs array (${configs.length})`
+      )
+    }
+  }
+
   configs.forEach((cfg, index) => {
-    let configType: "client" | "server" | "all" = "all"
+    let configType: string = "all"
 
     // Use outputs from build config if available
-    if (
-      buildOutputs.length > 0 &&
-      index < buildOutputs.length &&
-      buildOutputs[index]
-    ) {
-      const outputValue = buildOutputs[index]
-      // Validate the output value is a valid config type
-      if (
-        outputValue === "client" ||
-        outputValue === "server" ||
-        outputValue === "all"
-      ) {
-        configType = outputValue
-      } else {
-        throw new Error(
-          `Invalid output type '${outputValue}' at index ${index} in build '${buildName}'. ` +
-            `Allowed values are: client, server, all`
+    if (buildOutputs.length > 0) {
+      // If outputs are specified, skip configs beyond the outputs array
+      if (index >= buildOutputs.length) {
+        console.log(
+          `[Config Exporter] Skipping config[${index}] - beyond outputs array`
         )
+        return // Skip this config
       }
+
+      const outputValue = buildOutputs[index]
+      if (!outputValue || outputValue.trim() === "") {
+        return // Skip null/undefined/empty string entries
+      }
+
+      // Accept any string as a valid output name
+      // Built-in types: client, server, all, client-hmr
+      // Custom types: client-modern, client-legacy, server-bundle, etc.
+      configType = outputValue
     } else if (configs.length === 2) {
       // Likely client and server configs
       configType = index === 0 ? "client" : "server"
@@ -1285,7 +1421,8 @@ function formatConfig(
       appRoot
     })
     return serializer.serialize(config, metadata)
-  } else if (options.format === "json") {
+  }
+  if (options.format === "json") {
     const jsonReplacer = (key: string, value: any): any => {
       if (typeof value === "function") {
         return `[Function: ${value.name || "anonymous"}]`
@@ -1397,10 +1534,30 @@ function cleanConfig(obj: any, rootPath: string): any {
 /**
  * Loads and returns shakapacker.yml configuration
  */
+// Cache to avoid duplicate loading and logging
+let shakapackerConfigCache: {
+  env: string
+  result: { bundler: "webpack" | "rspack"; configPath: string }
+} | null = null
+
 function loadShakapackerConfig(
   env: string,
   appRoot: string
 ): { bundler: "webpack" | "rspack"; configPath: string } {
+  // Return cached result if same environment
+  if (shakapackerConfigCache && shakapackerConfigCache.env === env) {
+    if (process.env.VERBOSE) {
+      console.log(
+        `[Config Exporter] Using cached bundler config for env: ${env}`
+      )
+    }
+    return shakapackerConfigCache.result
+  }
+
+  if (process.env.VERBOSE) {
+    console.log(`[Config Exporter] Loading shakapacker config for env: ${env}`)
+  }
+
   try {
     const configFilePath =
       process.env.SHAKAPACKER_CONFIG ||
@@ -1416,10 +1573,12 @@ function loadShakapackerConfig(
         console.warn(
           `[Config Exporter] Invalid bundler '${bundler}' in shakapacker.yml, defaulting to webpack`
         )
-        return {
-          bundler: "webpack",
+        const result = {
+          bundler: "webpack" as const,
           configPath: bundler === "rspack" ? "config/rspack" : "config/webpack"
         }
+        shakapackerConfigCache = { env, result }
+        return result
       }
 
       // Get config path
@@ -1428,10 +1587,15 @@ function loadShakapackerConfig(
         customConfigPath ||
         (bundler === "rspack" ? "config/rspack" : "config/webpack")
 
+      const result = { bundler, configPath }
+      shakapackerConfigCache = { env, result }
+
+      // Only log on first call (when cache was empty)
       console.log(
         `[Config Exporter] Auto-detected bundler: ${bundler}, config path: ${configPath}`
       )
-      return { bundler, configPath }
+
+      return result
     }
   } catch (error: unknown) {
     console.warn(
@@ -1439,7 +1603,9 @@ function loadShakapackerConfig(
     )
   }
 
-  return { bundler: "webpack", configPath: "config/webpack" }
+  const result = { bundler: "webpack" as const, configPath: "config/webpack" }
+  shakapackerConfigCache = { env, result }
+  return result
 }
 
 /**

data/package/configExporter/fileWriter.ts

@@ -46,18 +46,27 @@ export class FileWriter {
    * Generate filename for a config export
    * Format without build: {bundler}-{env}-{type}.{ext}
    * Format with build: {bundler}-{build}-{type}.{ext}
-   * Examples:
-   *   webpack-development-client.yaml
-   *   rspack-production-server.yaml
-   *   webpack-test-all.json
-   *   webpack-development-client-hmr.yaml
-   *   webpack-dev-client.yaml (with build name)
-   *   rspack-cypress-dev-server.yaml (with build name)
+   *
+   * @param bundler - The bundler type (webpack, rspack)
+   * @param env - The environment (development, production, test)
+   * @param configType - Type of config. Built-in: "client", "server", "all", "client-hmr". Custom: any string from outputs array
+   * @param format - Output format (yaml, json, inspect)
+   * @param buildName - Optional build name that overrides env in filename
+   *
+   * @example
+   * // Built-in types
+   * generateFilename("webpack", "development", "client", "yaml")
+   * // => "webpack-development-client.yaml"
+   *
+   * @example
+   * // Custom output names
+   * generateFilename("webpack", "development", "client-modern", "yaml", "dev-hmr")
+   * // => "webpack-dev-hmr-client-modern.yaml"
    */
   static generateFilename(
     bundler: string,
     env: string,
-    configType: "client" | "server" | "all" | "client-hmr",
+    configType: string,
     format: "yaml" | "json" | "inspect",
     buildName?: string
   ): string {

data/package/configExporter/types.ts

@@ -29,7 +29,12 @@ export interface ConfigMetadata {
   bundler: string
   environment: string
   configFile: string
-  configType: "client" | "server" | "all" | "client-hmr"
+  /**
+   * Type of webpack/rspack config output.
+   * Built-in types: "client", "server", "all", "client-hmr"
+   * Custom types: Any string matching your outputs array (e.g., "client-modern", "client-legacy", "server-bundle")
+   */
+  configType: string
   configCount: number
   buildName?: string // New: name of the build from config file
   environmentVariables: {

data/package/utils/errorCodes.ts

@@ -165,6 +165,7 @@ export const ErrorMessages: Record<ErrorCode, string> = {
  */
 export class ShakapackerError extends Error {
   public readonly code: ErrorCode
+
   public readonly details?: Record<string, any>
 
   constructor(

data/package/utils/errorHelpers.ts

@@ -36,12 +36,14 @@ export function createFileOperationError(
   filePath: string,
   details?: string
 ): ShakapackerError {
-  const errorCode =
-    operation === "read"
-      ? ErrorCode.FILE_READ_ERROR
-      : operation === "write"
-        ? ErrorCode.FILE_WRITE_ERROR
-        : ErrorCode.FILE_NOT_FOUND
+  let errorCode: ErrorCode
+  if (operation === "read") {
+    errorCode = ErrorCode.FILE_READ_ERROR
+  } else if (operation === "write") {
+    errorCode = ErrorCode.FILE_WRITE_ERROR
+  } else {
+    errorCode = ErrorCode.FILE_NOT_FOUND
+  }
 
   return new ShakapackerError(errorCode, {
     path: filePath,
@@ -60,12 +62,14 @@ export function createFileOperationErrorLegacy(
 ): Error {
   const baseMessage = `Failed to ${operation} file at path '${filePath}'`
   const errorDetails = details ? ` - ${details}` : ""
-  const suggestion =
-    operation === "read"
-      ? " (check if file exists and permissions are correct)"
-      : operation === "write"
-        ? " (check write permissions and disk space)"
-        : " (check permissions)"
+  let suggestion: string
+  if (operation === "read") {
+    suggestion = " (check if file exists and permissions are correct)"
+  } else if (operation === "write") {
+    suggestion = " (check write permissions and disk space)"
+  } else {
+    suggestion = " (check permissions)"
+  }
   return new Error(`${baseMessage}${errorDetails}${suggestion}`)
 }
 

data/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "shakapacker",
-  "version": "9.3.0-beta.4",
+  "version": "9.3.0-beta.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "shakapacker",
-      "version": "9.3.0-beta.4",
+      "version": "9.3.0-beta.6",
       "license": "MIT",
       "dependencies": {
         "js-yaml": "^4.1.0",

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shakapacker",
-  "version": "9.3.0-beta.4",
+  "version": "9.3.0-beta.6",
   "description": "Use webpack to manage app-like JavaScript modules in Rails",
   "homepage": "https://github.com/shakacode/shakapacker",
   "bugs": {
@@ -32,7 +32,7 @@
   ],
   "scripts": {
     "clean:ts": "find package -name '*.ts' -not -name '*.d.ts' | sed 's/\\.ts$//' | xargs -I {} rm -f {}.js {}.d.ts {}.d.ts.map {}.js.map",
-    "build": "tsc && cp package/index.d.ts.template package/index.d.ts && node scripts/remove-use-strict.js && yarn prettier --write 'package/**/*.js'",
+    "build": "tsc && cp package/index.d.ts.template package/index.d.ts && node scripts/remove-use-strict.js && yarn prettier --write 'package/**/*.js' 'package/**/*.ts'",
     "build:types": "tsc",
     "knip": "knip",
     "knip:production": "knip --production",

data/scripts/remove-use-strict.js

@@ -41,5 +41,4 @@ files.forEach((file) => {
   fs.writeFileSync(file, content, "utf8")
 })
 
-// eslint-disable-next-line no-console
 console.log(`Removed "use strict" from ${files.length} files`)

data/test/package/configExporter.test.js

@@ -58,6 +58,51 @@ describe("configExporter", () => {
       )
       expect(filename).toBe("rspack-production-client.json")
     })
+
+    test("generates correct filename for custom output name client-modern", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "webpack",
+        "development",
+        "client-modern",
+        "yaml"
+      )
+      expect(filename).toBe("webpack-development-client-modern.yaml")
+    })
+
+    test("generates correct filename for custom output name client-legacy", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "webpack",
+        "production",
+        "client-legacy",
+        "yaml"
+      )
+      expect(filename).toBe("webpack-production-client-legacy.yaml")
+    })
+
+    test("generates correct filename for custom output name server-bundle", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "rspack",
+        "development",
+        "server-bundle",
+        "yaml"
+      )
+      expect(filename).toBe("rspack-development-server-bundle.yaml")
+    })
+
+    test("generates correct filename with buildName override", () => {
+      const { FileWriter } = require("../../package/configExporter/fileWriter")
+      const filename = FileWriter.generateFilename(
+        "webpack",
+        "development",
+        "client-modern",
+        "yaml",
+        "dev-hmr"
+      )
+      expect(filename).toBe("webpack-dev-hmr-client-modern.yaml")
+    })
   })
 
   describe("environment variable preservation in runDoctorMode", () => {

data/test/package/rules/babel.test.js

@@ -19,6 +19,7 @@ const babelConfig = require("../../../package/rules/babel")
 
 // Skip tests if babel config is not available (not the active transpiler)
 if (!babelConfig) {
+  // eslint-disable-next-line jest/no-disabled-tests
   describe.skip("babel - skipped", () => {
     test.todo("skipped because babel is not the active transpiler")
   })

data/test/package/rules/swc.test.js

@@ -19,6 +19,7 @@ const swcConfig = require("../../../package/rules/swc")
 
 // Skip tests if swc config is not available (not the active transpiler)
 if (!swcConfig) {
+  // eslint-disable-next-line jest/no-disabled-tests
   describe.skip("swc - skipped", () => {
     test.todo("skipped because swc is not the active transpiler")
   })

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shakapacker
 version: !ruby/object:Gem::Version
-  version: 9.3.0.beta.4
+  version: 9.3.0.beta.6
 platform: ruby
 authors:
 - David Heinemeier Hansson
@@ -180,6 +180,9 @@ files:
 - docs/customizing_babel_config.md
 - docs/deployment.md
 - docs/developing_shakapacker.md
+- docs/early_hints.md
+- docs/early_hints_manual_api.md
+- docs/feature_testing.md
 - docs/optional-peer-dependencies.md
 - docs/peer-dependencies.md
 - docs/precompile_hook.md
@@ -382,7 +385,7 @@ homepage: https://github.com/shakacode/shakapacker
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.3.0.beta.4
+  source_code_uri: https://github.com/shakacode/shakapacker/tree/v9.3.0.beta.6
 rdoc_options: []
 require_paths:
 - lib