shakapacker 9.0.0.beta.6 → 9.0.0.beta.8

data/package/rules/{file.js → file.ts}

@@ -1,21 +1,25 @@
-const { dirname, sep, normalize } = require("path")
+import { dirname, sep, normalize } from "path"
 const {
   additional_paths: additionalPaths,
   source_path: sourcePath
 } = require("../config")
 
-module.exports = {
+export = {
   test: /\.(bmp|gif|jpe?g|png|tiff|ico|avif|webp|eot|otf|ttf|woff|woff2|svg)$/,
   exclude: /\.(js|mjs|jsx|ts|tsx)$/,
   type: "asset/resource",
   generator: {
-    filename: (pathData) => {
+    filename: (pathData: { filename?: string }) => {
+      // Guard against null/undefined pathData or filename
+      if (!pathData || !pathData.filename) {
+        return `static/[name]-[hash][ext][query]`
+      }
       const path = normalize(dirname(pathData.filename))
-      const stripPaths = [...additionalPaths, sourcePath].map((p) =>
+      const stripPaths = [...additionalPaths, sourcePath].map((p: string) =>
         normalize(p)
       )
 
-      const selectedStripPath = stripPaths.find((includePath) =>
+      const selectedStripPath = stripPaths.find((includePath: string) =>
         path.startsWith(includePath)
       )
 
@@ -23,9 +27,10 @@ module.exports = {
         return `static/[name]-[hash][ext][query]`
       }
 
+      // Split on both forward and backward slashes for cross-platform compatibility
       const folders = path
         .replace(selectedStripPath, "")
-        .split(sep)
+        .split(/[\\/]/)
         .filter(Boolean)
 
       const foldersWithStatic = ["static", ...folders].join("/")

data/package/rules/{jscommon.js → jscommon.ts}

@@ -1,11 +1,11 @@
-const { resolve } = require("path")
-const { realpathSync } = require("fs")
+import { resolve } from "path"
+import { realpathSync } from "fs"
 const {
   source_path: sourcePath,
   additional_paths: additionalPaths
 } = require("../config")
 
-const inclusions = [sourcePath, ...additionalPaths].map((p) => {
+const inclusions = [sourcePath, ...additionalPaths].map((p: string) => {
   try {
     return realpathSync(p)
   } catch (e) {
@@ -13,7 +13,7 @@ const inclusions = [sourcePath, ...additionalPaths].map((p) => {
   }
 })
 
-module.exports = {
+export = {
   include: inclusions,
   exclude: [
     {

data/package/rules/{less.js → less.ts}

@@ -1,4 +1,3 @@
-const path = require("path")
 const { canProcess } = require("../utils/helpers")
 const { getStyleRule } = require("../utils/getStyleRule")
 
@@ -7,13 +6,14 @@ const {
   source_path: sourcePath
 } = require("../config")
 
-module.exports = canProcess("less-loader", (resolvedPath) =>
+export = canProcess("less-loader", (resolvedPath: string) =>
   getStyleRule(/\.(less)(\.erb)?$/i, [
     {
       loader: resolvedPath,
       options: {
         lessOptions: {
-          paths: [path.resolve(__dirname, "node_modules"), sourcePath, ...paths]
+          // Additional paths for Less imports (node_modules is resolved automatically)
+          paths: [sourcePath, ...paths]
         },
         sourceMap: true
       }

data/package/rules/raw.ts

@@ -0,0 +1,25 @@
+const config = require("../config")
+
+const rspackRawConfig = () => ({
+  resourceQuery: /raw/,
+  type: "asset/source"
+})
+
+const webpackRawConfig = () => ({
+  oneOf: [
+    {
+      // Match any file with ?raw query parameter
+      resourceQuery: /raw/,
+      type: "asset/source"
+    },
+    {
+      // Fallback: match .html files without query
+      test: /\.html$/,
+      exclude: /\.(js|mjs|jsx|ts|tsx)$/,
+      type: "asset/source"
+    }
+  ]
+})
+
+export =
+  config.assets_bundler === "rspack" ? rspackRawConfig() : webpackRawConfig()

data/package/rules/{rspack.js → rspack.ts}

@@ -141,26 +141,36 @@ if (erb) {
 }
 
 // File/asset handling using Rspack's built-in asset modules
+// This is a critical rule required for proper asset handling
 debug("Adding file/asset handling rule...")
 const file = require("./file")
 
-if (file) {
-  debug("Successfully added file/asset rule")
-  rules.push(file)
-} else {
-  warn("file rule configuration returned null")
+if (!file) {
+  throw new Error(
+    "CRITICAL: file rule configuration returned null. " +
+      "Asset handling is required for proper bundling. " +
+      "Please ensure the file rule module exports a valid rule configuration."
+  )
 }
 
+debug("Successfully added file/asset rule")
+rules.push(file)
+
 // Raw file loading
+// This is a critical rule required for raw file imports
 debug("Adding raw file loading rule...")
 const raw = require("./raw")
 
-if (raw) {
-  debug("Successfully added raw file rule")
-  rules.push(raw)
-} else {
-  warn("raw rule configuration returned null")
+if (!raw) {
+  throw new Error(
+    "CRITICAL: raw rule configuration returned null. " +
+      "Raw file loading is required for proper bundling. " +
+      "Please ensure the raw rule module exports a valid rule configuration."
+  )
 }
 
+debug("Successfully added raw file rule")
+rules.push(raw)
+
 debug(`Rspack rules configuration complete. Total rules: ${rules.length}`)
-module.exports = rules
+export = rules

data/package/rules/{sass.js → sass.ts}

@@ -4,7 +4,7 @@ const { getStyleRule } = require("../utils/getStyleRule")
 const { canProcess, packageMajorVersion } = require("../utils/helpers")
 const { additional_paths: extraPaths } = require("../config")
 
-module.exports = canProcess("sass-loader", (resolvedPath) => {
+export = canProcess("sass-loader", (resolvedPath: string) => {
   const optionKey =
     packageMajorVersion("sass-loader") > 15 ? "loadPaths" : "includePaths"
   return getStyleRule(/\.(scss|sass)(\.erb)?$/i, [

data/package/rules/{stylus.js → stylus.ts}

@@ -1,4 +1,3 @@
-const path = require("path")
 const { canProcess } = require("../utils/helpers")
 const { getStyleRule } = require("../utils/getStyleRule")
 
@@ -7,17 +6,14 @@ const {
   source_path: sourcePath
 } = require("../config")
 
-module.exports = canProcess("stylus-loader", (resolvedPath) =>
+export = canProcess("stylus-loader", (resolvedPath: string) =>
   getStyleRule(/\.(styl(us)?)(\.erb)?$/i, [
     {
       loader: resolvedPath,
       options: {
         stylusOptions: {
-          include: [
-            path.resolve(__dirname, "node_modules"),
-            sourcePath,
-            ...paths
-          ]
+          // Additional paths for Stylus imports (node_modules is resolved automatically)
+          include: [sourcePath, ...paths]
         },
         sourceMap: true
       }

data/package/rules/{swc.js → swc.ts}

@@ -3,8 +3,8 @@ const { getSwcLoaderConfig } = require("../swc")
 const { javascript_transpiler: javascriptTranspiler } = require("../config")
 const jscommon = require("./jscommon")
 
-module.exports = loaderMatches(javascriptTranspiler, "swc", () => ({
+export = loaderMatches(javascriptTranspiler, "swc", () => ({
   test: /\.(ts|tsx|js|jsx|mjs|coffee)?(\.erb)?$/,
   ...jscommon,
-  use: ({ resource }) => getSwcLoaderConfig(resource)
+  use: ({ resource }: { resource: string }) => getSwcLoaderConfig(resource)
 }))

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

@@ -1,7 +1,7 @@
 /* eslint global-require: 0 */
 /* eslint import/no-dynamic-require: 0 */
 
-module.exports = [
+export = [
   require("./raw"),
   require("./file"),
   require("./css"),

data/package/swc/index.ts

@@ -0,0 +1,54 @@
+/* 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 JSX_FILE_REGEX = /\.(jsx|tsx)(\.erb)?$/
+const TYPESCRIPT_FILE_REGEX = /\.(ts|tsx)(\.erb)?$/
+
+const isJsxFile = (filename: string): boolean => !!filename.match(JSX_FILE_REGEX)
+
+const isTypescriptFile = (filename: string): boolean => !!filename.match(TYPESCRIPT_FILE_REGEX)
+
+const getCustomConfig = (): Partial<RuleSetRule> => {
+  const path = resolve("config", "swc.config.js")
+  if (existsSync(path)) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(path)
+  }
+  return {}
+}
+
+const getSwcLoaderConfig = (filenameToProcess: string): RuleSetRule => {
+  const customConfig = getCustomConfig()
+  const isTs = isTypescriptFile(filenameToProcess)
+  const isJsx = isJsxFile(filenameToProcess)
+  const jsxKey = isTs ? "tsx" : "jsx"
+
+  const defaultConfig: RuleSetRule = {
+    loader: require.resolve("swc-loader"),
+    options: {
+      jsc: {
+        parser: {
+          dynamicImport: true,
+          syntax: isTs ? "typescript" : "ecmascript",
+          [jsxKey]: isJsx
+        },
+        loose: true
+      },
+      sourceMaps: true,
+      env: {
+        coreJs: 3,
+        exclude: ["transform-typeof-symbol"],
+        mode: "entry"
+      }
+    }
+  }
+
+  return merge(defaultConfig, customConfig)
+}
+
+export { getSwcLoaderConfig }

data/package/types/README.md

@@ -0,0 +1,87 @@
+# Shakapacker TypeScript Types
+
+This directory exports all TypeScript types used in Shakapacker for easier consumer imports.
+
+## Usage
+
+Instead of importing types from deep paths:
+
+```typescript
+// ❌ Old way - importing from multiple deep paths
+import type { Config } from 'shakapacker/package/types'
+import type { WebpackConfigWithDevServer } from 'shakapacker/package/environments/types'
+```
+
+You can now import all types from a single location:
+
+```typescript
+// ✅ New way - single import path
+import type {
+  Config,
+  WebpackConfigWithDevServer,
+  RspackConfigWithDevServer
+} from 'shakapacker/types'
+```
+
+## Available Types
+
+### Core Configuration Types
+- `Config` - Main Shakapacker configuration interface
+- `YamlConfig` - YAML configuration structure
+- `LegacyConfig` - Legacy configuration with deprecated options
+- `Env` - Environment variables interface
+- `DevServerConfig` - Development server configuration
+
+### Loader Types
+- `ShakapackerLoader` - Loader interface
+- `ShakapackerLoaderOptions` - Loader options interface
+- `LoaderResolver` - Function type for resolving loaders
+- `LoaderConfig` - Loader configuration interface
+
+### Webpack/Rspack Types
+- `WebpackConfigWithDevServer` - Webpack config with dev server
+- `RspackConfigWithDevServer` - Rspack config with dev server
+- `RspackPlugin` - Rspack plugin interface
+- `RspackDevServerConfig` - Rspack dev server configuration
+- `CompressionPluginOptions` - Options for compression plugin
+- `CompressionPluginConstructor` - Constructor type for compression plugin
+- `ReactRefreshWebpackPlugin` - React refresh plugin for Webpack
+- `ReactRefreshRspackPlugin` - React refresh plugin for Rspack
+
+### Webpack-Specific Types
+- `ShakapackerWebpackConfig` - Extended Webpack configuration
+- `ShakapackerRule` - Extended Webpack rule
+- `LoaderType` - String or loader object type
+- `LoaderUtils` - Loader utility functions
+
+### Re-exported Types
+- `WebpackConfiguration` - From 'webpack'
+- `WebpackPluginInstance` - From 'webpack'
+- `RuleSetRule` - From 'webpack'
+- `NodeJSError` - Node.js error exception type
+
+## Example Usage
+
+```typescript
+import type {
+  Config,
+  WebpackConfigWithDevServer
+} from 'shakapacker/types'
+
+const config: Config = {
+  source_path: 'app/javascript',
+  source_entry_path: 'packs',
+  public_root_path: 'public',
+  public_output_path: 'packs',
+  // ... other config
+}
+
+const webpackConfig: WebpackConfigWithDevServer = {
+  mode: 'development',
+  devServer: {
+    hot: true,
+    port: 3035
+  }
+  // ... other webpack config
+}
+```

data/package/types/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Central type exports for Shakapacker
+ * This file re-exports all public TypeScript types for easier consumer imports
+ *
+ * @example
+ * ```typescript
+ * import type { Config, WebpackConfigWithDevServer } from 'shakapacker/types'
+ * ```
+ *
+ * @module shakapacker/types
+ */
+
+// Core configuration types
+export type {
+  Config,
+  YamlConfig,
+  LegacyConfig,
+  Env,
+  DevServerConfig
+} from '../types'
+
+// Loader types
+export type {
+  ShakapackerLoader,
+  ShakapackerLoaderOptions,
+  LoaderResolver,
+  LoaderConfig
+} from '../loaders'
+
+// Webpack-specific types
+export type {
+  ShakapackerWebpackConfig,
+  ShakapackerRule,
+  ShakapackerLoaderOptions as WebpackLoaderOptions,
+  ShakapackerLoader as WebpackLoader,
+  LoaderType,
+  LoaderUtils
+} from '../webpack-types'
+
+// Environment configuration types
+export type {
+  WebpackConfigWithDevServer,
+  RspackPlugin,
+  RspackDevServerConfig,
+  RspackConfigWithDevServer,
+  CompressionPluginOptions,
+  CompressionPluginConstructor,
+  ReactRefreshWebpackPlugin,
+  ReactRefreshRspackPlugin
+} from '../environments/types'
+
+// Node.js error type (re-exported for convenience)
+export type NodeJSError = NodeJS.ErrnoException
+
+// Re-export commonly used webpack types for convenience
+export type {
+  Configuration as WebpackConfiguration,
+  WebpackPluginInstance,
+  RuleSetRule
+} from 'webpack'

data/package/utils/errorCodes.ts

@@ -0,0 +1,219 @@
+/**
+ * Error codes for programmatic error handling in Shakapacker
+ * These codes allow consumers to handle specific errors programmatically
+ * @module shakapacker/utils/errorCodes
+ */
+
+/**
+ * Error code enumeration for Shakapacker errors
+ */
+export enum ErrorCode {
+  // Configuration errors (1xxx)
+  CONFIG_NOT_FOUND = 'SHAKAPACKER_1001',
+  CONFIG_INVALID_YAML = 'SHAKAPACKER_1002',
+  CONFIG_MISSING_REQUIRED = 'SHAKAPACKER_1003',
+  CONFIG_VALIDATION_FAILED = 'SHAKAPACKER_1004',
+  CONFIG_MERGE_FAILED = 'SHAKAPACKER_1005',
+  CONFIG_TYPE_MISMATCH = 'SHAKAPACKER_1006',
+
+  // File system errors (2xxx)
+  FILE_NOT_FOUND = 'SHAKAPACKER_2001',
+  FILE_READ_ERROR = 'SHAKAPACKER_2002',
+  FILE_WRITE_ERROR = 'SHAKAPACKER_2003',
+  FILE_PERMISSION_DENIED = 'SHAKAPACKER_2004',
+  PATH_TRAVERSAL_DETECTED = 'SHAKAPACKER_2005',
+  INVALID_PATH = 'SHAKAPACKER_2006',
+
+  // Module errors (3xxx)
+  MODULE_NOT_FOUND = 'SHAKAPACKER_3001',
+  MODULE_LOAD_FAILED = 'SHAKAPACKER_3002',
+  MODULE_INVALID_EXPORT = 'SHAKAPACKER_3003',
+  LOADER_NOT_FOUND = 'SHAKAPACKER_3004',
+  PLUGIN_NOT_FOUND = 'SHAKAPACKER_3005',
+  PLUGIN_INVALID = 'SHAKAPACKER_3006',
+
+  // Environment errors (4xxx)
+  ENV_INVALID_NODE_ENV = 'SHAKAPACKER_4001',
+  ENV_MISSING_REQUIRED = 'SHAKAPACKER_4002',
+  ENV_INVALID_VALUE = 'SHAKAPACKER_4003',
+  ENV_SANITIZATION_REQUIRED = 'SHAKAPACKER_4004',
+
+  // Bundler errors (5xxx)
+  BUNDLER_UNSUPPORTED = 'SHAKAPACKER_5001',
+  BUNDLER_CONFIG_INVALID = 'SHAKAPACKER_5002',
+  WEBPACK_CONFIG_INVALID = 'SHAKAPACKER_5003',
+  RSPACK_CONFIG_INVALID = 'SHAKAPACKER_5004',
+  TRANSPILER_NOT_FOUND = 'SHAKAPACKER_5005',
+  TRANSPILER_CONFIG_INVALID = 'SHAKAPACKER_5006',
+
+  // Dev server errors (6xxx)
+  DEVSERVER_CONFIG_INVALID = 'SHAKAPACKER_6001',
+  DEVSERVER_PORT_INVALID = 'SHAKAPACKER_6002',
+  DEVSERVER_PORT_IN_USE = 'SHAKAPACKER_6003',
+  DEVSERVER_START_FAILED = 'SHAKAPACKER_6004',
+
+  // Security errors (7xxx)
+  SECURITY_PATH_TRAVERSAL = 'SHAKAPACKER_7001',
+  SECURITY_INVALID_INPUT = 'SHAKAPACKER_7002',
+  SECURITY_CONTROL_CHARS = 'SHAKAPACKER_7003',
+  SECURITY_INJECTION_ATTEMPT = 'SHAKAPACKER_7004',
+
+  // Validation errors (8xxx)
+  VALIDATION_FAILED = 'SHAKAPACKER_8001',
+  VALIDATION_TYPE_ERROR = 'SHAKAPACKER_8002',
+  VALIDATION_RANGE_ERROR = 'SHAKAPACKER_8003',
+  VALIDATION_FORMAT_ERROR = 'SHAKAPACKER_8004',
+  VALIDATION_CONSTRAINT_ERROR = 'SHAKAPACKER_8005',
+
+  // Generic errors (9xxx)
+  UNKNOWN_ERROR = 'SHAKAPACKER_9000',
+  INTERNAL_ERROR = 'SHAKAPACKER_9001',
+  DEPRECATED_FEATURE = 'SHAKAPACKER_9002',
+  NOT_IMPLEMENTED = 'SHAKAPACKER_9003',
+  OPERATION_FAILED = 'SHAKAPACKER_9004'
+}
+
+/**
+ * Error message templates for each error code
+ */
+export const ErrorMessages: Record<ErrorCode, string> = {
+  // Configuration errors
+  [ErrorCode.CONFIG_NOT_FOUND]: 'Configuration file not found: {path}',
+  [ErrorCode.CONFIG_INVALID_YAML]: 'Invalid YAML in configuration file: {path}',
+  [ErrorCode.CONFIG_MISSING_REQUIRED]: 'Missing required configuration field: {field}',
+  [ErrorCode.CONFIG_VALIDATION_FAILED]: 'Configuration validation failed: {reason}',
+  [ErrorCode.CONFIG_MERGE_FAILED]: 'Failed to merge configurations: {reason}',
+  [ErrorCode.CONFIG_TYPE_MISMATCH]: 'Configuration type mismatch for {field}: expected {expected}, got {actual}',
+
+  // File system errors
+  [ErrorCode.FILE_NOT_FOUND]: 'File not found: {path}',
+  [ErrorCode.FILE_READ_ERROR]: 'Error reading file: {path}',
+  [ErrorCode.FILE_WRITE_ERROR]: 'Error writing file: {path}',
+  [ErrorCode.FILE_PERMISSION_DENIED]: 'Permission denied accessing: {path}',
+  [ErrorCode.PATH_TRAVERSAL_DETECTED]: 'Path traversal attempt detected: {path}',
+  [ErrorCode.INVALID_PATH]: 'Invalid path: {path}',
+
+  // Module errors
+  [ErrorCode.MODULE_NOT_FOUND]: 'Module not found: {module}',
+  [ErrorCode.MODULE_LOAD_FAILED]: 'Failed to load module: {module}',
+  [ErrorCode.MODULE_INVALID_EXPORT]: 'Invalid export from module: {module}',
+  [ErrorCode.LOADER_NOT_FOUND]: 'Loader not found: {loader}',
+  [ErrorCode.PLUGIN_NOT_FOUND]: 'Plugin not found: {plugin}',
+  [ErrorCode.PLUGIN_INVALID]: 'Invalid plugin: {plugin}',
+
+  // Environment errors
+  [ErrorCode.ENV_INVALID_NODE_ENV]: 'Invalid NODE_ENV value: {value}. Valid values are: {valid}',
+  [ErrorCode.ENV_MISSING_REQUIRED]: 'Missing required environment variable: {variable}',
+  [ErrorCode.ENV_INVALID_VALUE]: 'Invalid value for environment variable {variable}: {value}',
+  [ErrorCode.ENV_SANITIZATION_REQUIRED]: 'Environment variable {variable} contained unsafe characters and was sanitized',
+
+  // Bundler errors
+  [ErrorCode.BUNDLER_UNSUPPORTED]: 'Unsupported bundler: {bundler}',
+  [ErrorCode.BUNDLER_CONFIG_INVALID]: 'Invalid bundler configuration: {reason}',
+  [ErrorCode.WEBPACK_CONFIG_INVALID]: 'Invalid webpack configuration: {reason}',
+  [ErrorCode.RSPACK_CONFIG_INVALID]: 'Invalid rspack configuration: {reason}',
+  [ErrorCode.TRANSPILER_NOT_FOUND]: 'Transpiler not found: {transpiler}',
+  [ErrorCode.TRANSPILER_CONFIG_INVALID]: 'Invalid transpiler configuration: {reason}',
+
+  // Dev server errors
+  [ErrorCode.DEVSERVER_CONFIG_INVALID]: 'Invalid dev server configuration: {reason}',
+  [ErrorCode.DEVSERVER_PORT_INVALID]: 'Invalid port: {port}',
+  [ErrorCode.DEVSERVER_PORT_IN_USE]: 'Port {port} is already in use',
+  [ErrorCode.DEVSERVER_START_FAILED]: 'Failed to start dev server: {reason}',
+
+  // Security errors
+  [ErrorCode.SECURITY_PATH_TRAVERSAL]: 'Security: Path traversal attempt blocked: {path}',
+  [ErrorCode.SECURITY_INVALID_INPUT]: 'Security: Invalid input detected: {input}',
+  [ErrorCode.SECURITY_CONTROL_CHARS]: 'Security: Control characters detected and removed from: {field}',
+  [ErrorCode.SECURITY_INJECTION_ATTEMPT]: 'Security: Potential injection attempt blocked: {details}',
+
+  // Validation errors
+  [ErrorCode.VALIDATION_FAILED]: 'Validation failed: {reason}',
+  [ErrorCode.VALIDATION_TYPE_ERROR]: 'Type validation error: {field} should be {type}',
+  [ErrorCode.VALIDATION_RANGE_ERROR]: 'Value out of range: {field} must be between {min} and {max}',
+  [ErrorCode.VALIDATION_FORMAT_ERROR]: 'Format error: {field} does not match expected format',
+  [ErrorCode.VALIDATION_CONSTRAINT_ERROR]: 'Constraint violation: {constraint}',
+
+  // Generic errors
+  [ErrorCode.UNKNOWN_ERROR]: 'An unknown error occurred',
+  [ErrorCode.INTERNAL_ERROR]: 'Internal error: {details}',
+  [ErrorCode.DEPRECATED_FEATURE]: 'Deprecated feature: {feature}. Use {alternative} instead',
+  [ErrorCode.NOT_IMPLEMENTED]: 'Feature not yet implemented: {feature}',
+  [ErrorCode.OPERATION_FAILED]: 'Operation failed: {operation}'
+}
+
+/**
+ * Shakapacker error class with error code support
+ */
+export class ShakapackerError extends Error {
+  public readonly code: ErrorCode
+  public readonly details?: Record<string, any>
+
+  constructor(code: ErrorCode, details?: Record<string, any>, customMessage?: string) {
+    const template = ErrorMessages[code] || 'An error occurred'
+    const message = customMessage || ShakapackerError.formatMessage(template, details)
+
+    super(message)
+    this.name = 'ShakapackerError'
+    this.code = code
+    this.details = details
+
+    // Maintain proper stack trace for where error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ShakapackerError)
+    }
+  }
+
+  /**
+   * Format error message with template values
+   */
+  private static formatMessage(template: string, details?: Record<string, any>): string {
+    if (!details) return template
+
+    return template.replace(/{(\w+)}/g, (match, key) => {
+      const value = details[key]
+      if (value === undefined) return match
+      if (typeof value === 'object') {
+        return JSON.stringify(value)
+      }
+      return String(value)
+    })
+  }
+
+  /**
+   * Convert error to JSON for logging or API responses
+   */
+  toJSON(): Record<string, any> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      stack: this.stack
+    }
+  }
+}
+
+/**
+ * Helper function to create a Shakapacker error
+ */
+export function createError(code: ErrorCode, details?: Record<string, any>): ShakapackerError {
+  return new ShakapackerError(code, details)
+}
+
+/**
+ * Helper function to check if an error is a Shakapacker error
+ */
+export function isShakapackerError(error: unknown): error is ShakapackerError {
+  return error instanceof ShakapackerError
+}
+
+/**
+ * Helper function to get error code from any error
+ */
+export function getErrorCode(error: unknown): ErrorCode | null {
+  if (isShakapackerError(error)) {
+    return error.code
+  }
+  return null
+}