shakapacker 9.2.0 → 9.3.0.beta.0

data/docs/transpiler-performance.md

@@ -4,15 +4,16 @@ This document provides performance benchmarks comparing different JavaScript tra
 
 ## Executive Summary
 
-| Transpiler | Relative Speed | Configuration | Best For |
-|------------|---------------|---------------|----------|
-| **SWC** | **20x faster** | Zero config | Production builds, large codebases |
-| **esbuild** | **15x faster** | Minimal config | Modern browsers, simple transformations |
-| **Babel** | **Baseline** | Extensive config | Legacy browser support, custom transformations |
+| Transpiler  | Relative Speed | Configuration    | Best For                                       |
+| ----------- | -------------- | ---------------- | ---------------------------------------------- |
+| **SWC**     | **20x faster** | Zero config      | Production builds, large codebases             |
+| **esbuild** | **15x faster** | Minimal config   | Modern browsers, simple transformations        |
+| **Babel**   | **Baseline**   | Extensive config | Legacy browser support, custom transformations |
 
 ## Detailed Benchmarks
 
 ### Test Environment
+
 - **Hardware**: MacBook Pro M1, 16GB RAM
 - **Node Version**: 20.x
 - **Project Size Categories**:
@@ -23,6 +24,7 @@ This document provides performance benchmarks comparing different JavaScript tra
 ### Build Time Comparison
 
 #### Small Project (<100 files, ~50KB total)
+
 ```text
 SWC:      0.3s  (20x faster)
 esbuild:  0.4s  (15x faster)
@@ -30,6 +32,7 @@ Babel:    6.0s  (baseline)
 ```
 
 #### Medium Project (500 files, ~2MB total)
+
 ```text
 SWC:      1.2s  (25x faster)
 esbuild:  1.8s  (17x faster)
@@ -37,6 +40,7 @@ Babel:    30s   (baseline)
 ```
 
 #### Large Project (2000 files, ~10MB total)
+
 ```text
 SWC:      4.5s  (22x faster)
 esbuild:  6.2s  (16x faster)
@@ -45,25 +49,26 @@ Babel:    100s  (baseline)
 
 ### Memory Usage
 
-| Transpiler | Peak Memory (Small) | Peak Memory (Medium) | Peak Memory (Large) |
-|------------|-------------------|---------------------|-------------------|
-| **SWC** | 150MB | 250MB | 450MB |
-| **esbuild** | 180MB | 300MB | 500MB |
-| **Babel** | 350MB | 600MB | 1200MB |
+| Transpiler  | Peak Memory (Small) | Peak Memory (Medium) | Peak Memory (Large) |
+| ----------- | ------------------- | -------------------- | ------------------- |
+| **SWC**     | 150MB               | 250MB                | 450MB               |
+| **esbuild** | 180MB               | 300MB                | 500MB               |
+| **Babel**   | 350MB               | 600MB                | 1200MB              |
 
 ## Incremental Build Performance
 
 For development with watch mode enabled:
 
-| Transpiler | Initial Build | Incremental Build | HMR Update |
-|------------|--------------|------------------|------------|
-| **SWC** | 1.2s | 0.1s | <50ms |
-| **esbuild** | 1.8s | 0.15s | <70ms |
-| **Babel** | 30s | 2-5s | 200-500ms |
+| Transpiler  | Initial Build | Incremental Build | HMR Update |
+| ----------- | ------------- | ----------------- | ---------- |
+| **SWC**     | 1.2s          | 0.1s              | <50ms      |
+| **esbuild** | 1.8s          | 0.15s             | <70ms      |
+| **Babel**   | 30s           | 2-5s              | 200-500ms  |
 
 ## Feature Comparison
 
 ### SWC
+
 - ✅ TypeScript support built-in
 - ✅ JSX/TSX transformation
 - ✅ Minification built-in
@@ -73,6 +78,7 @@ For development with watch mode enabled:
 - ⚠️ Newer, less battle-tested
 
 ### esbuild
+
 - ✅ TypeScript support built-in
 - ✅ JSX transformation
 - ✅ Extremely fast bundling
@@ -81,6 +87,7 @@ For development with watch mode enabled:
 - ❌ No plugin system for custom transforms
 
 ### Babel
+
 - ✅ Most comprehensive browser support
 - ✅ Extensive plugin ecosystem
 - ✅ Custom transformation support
@@ -91,6 +98,7 @@ For development with watch mode enabled:
 ## Recommendations by Use Case
 
 ### Choose SWC when:
+
 - Performance is critical
 - Using modern JavaScript/TypeScript
 - Building large applications
@@ -98,12 +106,14 @@ For development with watch mode enabled:
 - Default choice for new projects
 
 ### Choose esbuild when:
+
 - Need the absolute fastest builds
 - Targeting modern browsers only
 - Simple transformation requirements
 - Minimal configuration preferred
 
 ### Choose Babel when:
+
 - Need extensive browser compatibility (IE11, etc.)
 - Using experimental JavaScript features
 - Require specific Babel plugins
@@ -112,6 +122,7 @@ For development with watch mode enabled:
 ## Migration Impact
 
 ### From Babel to SWC
+
 - **Build time reduction**: 90-95%
 - **Memory usage reduction**: 50-70%
 - **Configuration simplification**: 80% less config
@@ -120,16 +131,19 @@ For development with watch mode enabled:
 ### Real-world Examples
 
 #### E-commerce Platform (1500 components)
+
 - **Before (Babel)**: 120s production build
 - **After (SWC)**: 5.5s production build
 - **Improvement**: 95.4% faster
 
 #### SaaS Dashboard (800 files)
+
 - **Before (Babel)**: 45s development build
 - **After (SWC)**: 2.1s development build
 - **Improvement**: 95.3% faster
 
 #### Blog Platform (200 files)
+
 - **Before (Babel)**: 15s build time
 - **After (SWC)**: 0.8s build time
 - **Improvement**: 94.7% faster
@@ -137,28 +151,34 @@ For development with watch mode enabled:
 ## How to Switch Transpilers
 
 ### To SWC (Recommended)
+
 ```yaml
 # config/shakapacker.yml
-javascript_transpiler: 'swc'
+javascript_transpiler: "swc"
 ```
+
 ```bash
 npm install @swc/core swc-loader
 ```
 
 ### To esbuild
+
 ```yaml
 # config/shakapacker.yml
-javascript_transpiler: 'esbuild'
+javascript_transpiler: "esbuild"
 ```
+
 ```bash
 npm install esbuild esbuild-loader
 ```
 
 ### To Babel
+
 ```yaml
 # config/shakapacker.yml
-javascript_transpiler: 'babel'
+javascript_transpiler: "babel"
 ```
+
 ```bash
 npm install babel-loader @babel/core @babel/preset-env
 ```
@@ -166,6 +186,7 @@ npm install babel-loader @babel/core @babel/preset-env
 ## Testing Methodology
 
 Benchmarks were conducted using:
+
 1. Clean builds (no cache)
 2. Average of 10 runs
 3. Same source code for all transpilers
@@ -176,4 +197,4 @@ Benchmarks were conducted using:
 
 For most projects, **SWC provides the best balance** of performance, features, and ease of use. It offers a 20x performance improvement over Babel with minimal configuration required.
 
-Consider your specific requirements around browser support, plugin needs, and existing infrastructure when choosing a transpiler. The performance gains from switching to SWC or esbuild can significantly improve developer productivity and CI/CD pipeline efficiency.
+Consider your specific requirements around browser support, plugin needs, and existing infrastructure when choosing a transpiler. The performance gains from switching to SWC or esbuild can significantly improve developer productivity and CI/CD pipeline efficiency.

data/docs/troubleshooting.md

@@ -18,7 +18,6 @@
 4. You can also pass additional options to the command to run the webpack-dev-server and start the webpack-dev-server with the option `--debug-shakapacker`
 
 5. **Export your full webpack/rspack configuration for analysis**: Use the `bin/export-bundler-config` utility to export your complete resolved configuration. This is especially helpful for:
-
    - **Migrations**: Comparing configurations before and after migrating between webpack and rspack, or between different Shakapacker versions
    - **Debugging**: Inspecting the exact configuration webpack/rspack is using, including all merged settings
    - **AI Analysis**: Uploading the exported config to ChatGPT or other AI tools for troubleshooting
@@ -66,7 +65,6 @@
    ```
 
    **Config files are automatically named:** `{bundler}-{env}-{type}.{ext}`
-
    - Examples: `webpack-development-client.yaml`, `rspack-production-server.yaml`
    - YAML format includes inline documentation explaining each config key
    - Separate files for client and server bundles (cleaner than combined)

data/docs/typescript-migration.md

@@ -3,6 +3,7 @@
 This guide helps you adopt TypeScript types in your Shakapacker configuration files for better type safety and IDE support.
 
 ## Table of Contents
+
 - [Benefits](#benefits)
 - [Quick Start](#quick-start)
 - [Migration Steps](#migration-steps)
@@ -12,6 +13,7 @@ This guide helps you adopt TypeScript types in your Shakapacker configuration fi
 ## Benefits
 
 Using TypeScript with Shakapacker provides:
+
 - **Type Safety**: Catch configuration errors at compile time
 - **IDE Support**: Get autocompletion and inline documentation
 - **Better Refactoring**: Safely rename and restructure configurations
@@ -56,13 +58,13 @@ Rename `config/webpack/webpack.config.js` to `config/webpack/webpack.config.ts`:
 
 ```typescript
 // config/webpack/webpack.config.ts
-import { generateWebpackConfig, merge } from 'shakapacker'
-import type { WebpackConfigWithDevServer } from 'shakapacker/types'
-import type { Configuration } from 'webpack'
+import { generateWebpackConfig, merge } from "shakapacker"
+import type { WebpackConfigWithDevServer } from "shakapacker/types"
+import type { Configuration } from "webpack"
 
 const customConfig: Configuration = {
   resolve: {
-    extensions: ['.css', '.ts', '.tsx']
+    extensions: [".css", ".ts", ".tsx"]
   }
 }
 
@@ -83,7 +85,7 @@ import type {
   WebpackConfigWithDevServer,
   RspackConfigWithDevServer,
   CompressionPluginOptions
-} from 'shakapacker/types'
+} from "shakapacker/types"
 ```
 
 ### Step 2: Type Your Configuration Objects
@@ -94,16 +96,16 @@ Add type annotations to your configuration objects:
 // Before (JavaScript)
 const customConfig = {
   resolve: {
-    extensions: ['.css', '.ts', '.tsx']
+    extensions: [".css", ".ts", ".tsx"]
   }
 }
 
 // After (TypeScript)
-import type { Configuration } from 'webpack'
+import type { Configuration } from "webpack"
 
 const customConfig: Configuration = {
   resolve: {
-    extensions: ['.css', '.ts', '.tsx']
+    extensions: [".css", ".ts", ".tsx"]
   }
 }
 ```
@@ -120,8 +122,8 @@ function modifyConfig(config) {
 }
 
 // After (TypeScript)
-import type { Configuration } from 'webpack'
-import type { WebpackPluginInstance } from 'shakapacker/types'
+import type { Configuration } from "webpack"
+import type { WebpackPluginInstance } from "shakapacker/types"
 
 function modifyConfig(config: Configuration): Configuration {
   const plugins = config.plugins as WebpackPluginInstance[]
@@ -134,11 +136,11 @@ function modifyConfig(config: Configuration): Configuration {
 
 ```typescript
 // config/webpack/development.ts
-import { generateWebpackConfig } from 'shakapacker'
-import type { WebpackConfigWithDevServer } from 'shakapacker/types'
+import { generateWebpackConfig } from "shakapacker"
+import type { WebpackConfigWithDevServer } from "shakapacker/types"
 
 const developmentConfig: WebpackConfigWithDevServer = generateWebpackConfig({
-  devtool: 'eval-cheap-module-source-map',
+  devtool: "eval-cheap-module-source-map",
   devServer: {
     hot: true,
     port: 3035
@@ -153,11 +155,11 @@ export default developmentConfig
 ### Pattern 1: Custom Loaders
 
 ```typescript
-import type { RuleSetRule } from 'webpack'
+import type { RuleSetRule } from "webpack"
 
 const customLoader: RuleSetRule = {
   test: /\.svg$/,
-  use: ['@svgr/webpack']
+  use: ["@svgr/webpack"]
 }
 
 const config: Configuration = generateWebpackConfig({
@@ -170,12 +172,12 @@ const config: Configuration = generateWebpackConfig({
 ### Pattern 2: Plugin Configuration
 
 ```typescript
-import CompressionPlugin from 'compression-webpack-plugin'
-import type { CompressionPluginOptions } from 'shakapacker/types'
+import CompressionPlugin from "compression-webpack-plugin"
+import type { CompressionPluginOptions } from "shakapacker/types"
 
 const compressionOptions: CompressionPluginOptions = {
-  filename: '[path][base].gz',
-  algorithm: 'gzip',
+  filename: "[path][base].gz",
+  algorithm: "gzip",
   test: /\.(js|css|html|json|ico|svg|eot|otf|ttf)$/
 }
 
@@ -187,8 +189,8 @@ const config: Configuration = generateWebpackConfig({
 ### Pattern 3: Conditional Configuration
 
 ```typescript
-import type { Configuration } from 'webpack'
-import { env } from 'shakapacker'
+import type { Configuration } from "webpack"
+import { env } from "shakapacker"
 
 const config: Configuration = generateWebpackConfig()
 
@@ -208,11 +210,11 @@ export default config
 
 ```typescript
 // config/rspack/rspack.config.ts
-import type { RspackConfigWithDevServer } from 'shakapacker/types'
-import { generateWebpackConfig } from 'shakapacker'
+import type { RspackConfigWithDevServer } from "shakapacker/types"
+import { generateWebpackConfig } from "shakapacker"
 
 const rspackConfig: RspackConfigWithDevServer = generateWebpackConfig({
-  mode: 'development',
+  mode: "development",
   devServer: {
     hot: true,
     port: 3036
@@ -246,11 +248,13 @@ npm run type-check
 ## Available Types Reference
 
 ### Core Types
+
 - `Config` - Shakapacker configuration from shakapacker.yml
 - `Env` - Environment variables and helpers
 - `DevServerConfig` - Development server configuration
 
 ### Webpack/Rspack Types
+
 - `WebpackConfigWithDevServer` - Webpack configuration with dev server
 - `RspackConfigWithDevServer` - Rspack configuration with dev server
 - `WebpackPluginInstance` - Webpack plugin instance type
@@ -258,6 +262,7 @@ npm run type-check
 - `RspackPlugin` - **⚠️ Deprecated:** Use `RspackPluginInstance` instead
 
 ### Helper Types
+
 - `CompressionPluginOptions` - Compression plugin configuration
 - `ReactRefreshWebpackPlugin` - React refresh for Webpack
 - `ReactRefreshRspackPlugin` - React refresh for Rspack
@@ -287,7 +292,7 @@ plugins.push(new MyPlugin())
 
 ```typescript
 // If types aren't available, declare them
-declare module 'my-custom-loader' {
+declare module "my-custom-loader" {
   const loader: any
   export default loader
 }
@@ -316,27 +321,31 @@ Here's a complete example of a typed webpack configuration:
 
 ```typescript
 // config/webpack/webpack.config.ts
-import { generateWebpackConfig, merge, config as shakapackerConfig } from 'shakapacker'
-import type { Configuration } from 'webpack'
-import type { WebpackConfigWithDevServer } from 'shakapacker/types'
-import CompressionPlugin from 'compression-webpack-plugin'
-import { resolve } from 'path'
+import {
+  generateWebpackConfig,
+  merge,
+  config as shakapackerConfig
+} from "shakapacker"
+import type { Configuration } from "webpack"
+import type { WebpackConfigWithDevServer } from "shakapacker/types"
+import CompressionPlugin from "compression-webpack-plugin"
+import { resolve } from "path"
 
 // Type-safe custom configuration
 const customConfig: Configuration = {
   resolve: {
-    extensions: ['.css', '.ts', '.tsx'],
+    extensions: [".css", ".ts", ".tsx"],
     alias: {
-      '@': resolve(__dirname, '../../app/javascript'),
-      'components': resolve(__dirname, '../../app/javascript/components'),
-      'utils': resolve(__dirname, '../../app/javascript/utils')
+      "@": resolve(__dirname, "../../app/javascript"),
+      components: resolve(__dirname, "../../app/javascript/components"),
+      utils: resolve(__dirname, "../../app/javascript/utils")
     }
   },
   module: {
     rules: [
       {
         test: /\.svg$/,
-        use: ['@svgr/webpack'],
+        use: ["@svgr/webpack"],
         issuer: /\.(tsx?|jsx?)$/
       }
     ]
@@ -347,13 +356,13 @@ const customConfig: Configuration = {
 const webpackConfig: Configuration = generateWebpackConfig(customConfig)
 
 // Type-safe modifications based on environment
-if (shakapackerConfig.env === 'production') {
+if (shakapackerConfig.env === "production") {
   const plugins = (webpackConfig.plugins || []) as WebpackPluginInstance[]
 
   plugins.push(
     new CompressionPlugin({
-      filename: '[path][base].br',
-      algorithm: 'brotliCompress',
+      filename: "[path][base].br",
+      algorithm: "brotliCompress",
       test: /\.(js|css|html|json|ico|svg|eot|otf|ttf)$/
     })
   )
@@ -376,4 +385,4 @@ After migrating to TypeScript:
 - [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html)
 - [Webpack TypeScript Configuration](https://webpack.js.org/configuration/configuration-languages/#typescript)
 - [Shakapacker Types Documentation](./types/README.md)
-- [Migration Examples](https://github.com/shakacode/shakapacker/tree/main/examples/typescript-config)
+- [Migration Examples](https://github.com/shakacode/shakapacker/tree/main/examples/typescript-config)

data/docs/typescript.md

@@ -8,8 +8,8 @@ Shakapacker v9 includes TypeScript support, providing type safety and better IDE
 
 ```typescript
 // webpack.config.ts
-import { generateWebpackConfig } from 'shakapacker'
-import type { Configuration } from 'webpack'
+import { generateWebpackConfig } from "shakapacker"
+import type { Configuration } from "webpack"
 
 const config: Configuration = generateWebpackConfig({
   // Your config with full type safety
@@ -22,7 +22,7 @@ export default config
 
 ```javascript
 // webpack.config.js
-const { generateWebpackConfig } = require('shakapacker')
+const { generateWebpackConfig } = require("shakapacker")
 
 /** @type {import('webpack').Configuration} */
 const config = {
@@ -48,10 +48,12 @@ module.exports = generateWebpackConfig(config)
 ## IDE Setup
 
 ### VS Code
+
 - Install TypeScript extension (built-in)
 - Set `"typescript.tsdk": "node_modules/typescript/lib"` in settings
 
 ### WebStorm/IntelliJ
+
 - Enable TypeScript service in Settings → Languages & Frameworks → TypeScript
 
 ## Common Patterns
@@ -59,7 +61,7 @@ module.exports = generateWebpackConfig(config)
 ### Environment-Specific Config
 
 ```typescript
-import { generateWebpackConfig, env } from 'shakapacker'
+import { generateWebpackConfig, env } from "shakapacker"
 
 const config = generateWebpackConfig({
   optimization: {
@@ -71,8 +73,8 @@ const config = generateWebpackConfig({
 ### Rspack Config
 
 ```typescript
-import { generateRspackConfig } from 'shakapacker/rspack'
-import type { RspackOptions } from '@rspack/core'
+import { generateRspackConfig } from "shakapacker/rspack"
+import type { RspackOptions } from "@rspack/core"
 
 const config: RspackOptions = {
   // Rspack-specific config
@@ -84,16 +86,18 @@ export default generateRspackConfig(config)
 ## Troubleshooting
 
 **Cannot find module 'shakapacker'**
+
 ```typescript
 /// <reference types="shakapacker" />
 ```
 
 **Type errors with custom loaders**
+
 ```typescript
-use: [require.resolve('custom-loader') as any]
+use: [require.resolve("custom-loader") as any]
 ```
 
 ## Further Reading
 
 - [Webpack TypeScript Documentation](https://webpack.js.org/configuration/configuration-languages/#typescript)
-- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

data/docs/using_esbuild_loader.md

@@ -11,6 +11,7 @@ If you face any issues, please report them at https://github.com/shakacode/shaka
 While esbuild is a complete bundler, through the usage of [esbuild-loader](https://github.com/privatenumber/esbuild-loader), you can still leverage esbuild's speedy transpilation and minification in your Webpack-based configs.
 
 Please note, that unlike Babel or SWC loader, esbuild-loader has got no support for things like:
+
 - React Hot Module reload
 - ES5 as a compilation target
 - Automatic polyfills for missing browser features
@@ -28,7 +29,7 @@ npm install esbuild esbuild-loader
 ```
 
 2. Add or change `javascript_transpiler` value in your default `shakapacker.yml` config to `esbuild`
-The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
+   The default configuration of babel is done by using `package.json` to use the file within the `shakapacker` package.
 
 ```yml
 default: &default
@@ -47,7 +48,7 @@ default: &default
   cache_manifest: false
 
   # Select JavaScript transpiler to use, available options are 'babel' (default), 'swc' or 'esbuild'
-  javascript_transpiler: 'esbuild'
+  javascript_transpiler: "esbuild"
 ```
 
 ### (Optional) Replace minification with esbuild
@@ -59,14 +60,14 @@ o do so, you need to modify your webpack configuration and use `ESBuildMinifyPlu
 Example:
 
 ```js
-const { generateWebpackConfig } = require('shakapacker')
-const { ESBuildMinifyPlugin } = require('esbuild-loader')
+const { generateWebpackConfig } = require("shakapacker")
+const { ESBuildMinifyPlugin } = require("esbuild-loader")
 
 const options = {
   optimization: {
     minimizer: [
       new ESBuildMinifyPlugin({
-        target: 'es2015' 
+        target: "es2015"
       })
     ]
   }
@@ -101,11 +102,10 @@ See some examples below of potential `config/babel.config.js`.
 
 ### Example: Specifying esnext target environment
 
-
 ```js
 const customConfig = {
   options: {
-    target: 'esnext'
+    target: "esnext"
   }
 }
 
@@ -115,12 +115,12 @@ module.exports = customConfig
 ### Example: Using custom jsxFragment and jsxFactory
 
 ```js
-const { env } = require('shakapacker')
+const { env } = require("shakapacker")
 
 const customConfig = {
   options: {
-    jsxFragment: 'Fragment',
-    jsxFactory: 'h' 
+    jsxFragment: "Fragment",
+    jsxFactory: "h"
   }
 }