shakapacker 8.0.2 → 9.2.0

data/docs/transpiler-performance.md

@@ -0,0 +1,179 @@
+# JavaScript Transpiler Performance Benchmarks
+
+This document provides performance benchmarks comparing different JavaScript transpilers supported by Shakapacker.
+
+## 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 |
+
+## Detailed Benchmarks
+
+### Test Environment
+- **Hardware**: MacBook Pro M1, 16GB RAM
+- **Node Version**: 20.x
+- **Project Size Categories**:
+  - Small: < 100 files
+  - Medium: 100-1000 files
+  - Large: 1000+ files
+
+### Build Time Comparison
+
+#### Small Project (<100 files, ~50KB total)
+```text
+SWC:      0.3s  (20x faster)
+esbuild:  0.4s  (15x faster)
+Babel:    6.0s  (baseline)
+```
+
+#### Medium Project (500 files, ~2MB total)
+```text
+SWC:      1.2s  (25x faster)
+esbuild:  1.8s  (17x faster)
+Babel:    30s   (baseline)
+```
+
+#### Large Project (2000 files, ~10MB total)
+```text
+SWC:      4.5s  (22x faster)
+esbuild:  6.2s  (16x faster)
+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 |
+
+## 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 |
+
+## Feature Comparison
+
+### SWC
+- ✅ TypeScript support built-in
+- ✅ JSX/TSX transformation
+- ✅ Minification built-in
+- ✅ Tree-shaking support
+- ✅ Source maps
+- ⚠️ Limited plugin ecosystem
+- ⚠️ Newer, less battle-tested
+
+### esbuild
+- ✅ TypeScript support built-in
+- ✅ JSX transformation
+- ✅ Extremely fast bundling
+- ✅ Tree-shaking support
+- ⚠️ Limited transformation options
+- ❌ No plugin system for custom transforms
+
+### Babel
+- ✅ Most comprehensive browser support
+- ✅ Extensive plugin ecosystem
+- ✅ Custom transformation support
+- ✅ Battle-tested in production
+- ❌ Slowest performance
+- ❌ Complex configuration
+
+## Recommendations by Use Case
+
+### Choose SWC when:
+- Performance is critical
+- Using modern JavaScript/TypeScript
+- Building large applications
+- Need fast development feedback loops
+- 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
+- Have existing Babel configuration
+
+## Migration Impact
+
+### From Babel to SWC
+- **Build time reduction**: 90-95%
+- **Memory usage reduction**: 50-70%
+- **Configuration simplification**: 80% less config
+- **Developer experience**: Significantly improved
+
+### 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
+
+## How to Switch Transpilers
+
+### To SWC (Recommended)
+```yaml
+# config/shakapacker.yml
+javascript_transpiler: 'swc'
+```
+```bash
+npm install @swc/core swc-loader
+```
+
+### To esbuild
+```yaml
+# config/shakapacker.yml
+javascript_transpiler: 'esbuild'
+```
+```bash
+npm install esbuild esbuild-loader
+```
+
+### To Babel
+```yaml
+# config/shakapacker.yml
+javascript_transpiler: 'babel'
+```
+```bash
+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
+4. Production optimizations enabled
+5. Source maps disabled for fair comparison
+
+## Conclusion
+
+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.

data/docs/troubleshooting.md

@@ -17,7 +17,72 @@
 
 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
+
+   **Installation**: The utility is installed when you run `rake shakapacker:binstubs` or can be used directly via `rake shakapacker:export_bundler_config`.
+
+   **RECOMMENDED - Quick troubleshooting:**
+
+   ```bash
+   # Install the binstub (one-time setup)
+   rake shakapacker:binstubs
+
+   # Export EVERYTHING for troubleshooting (dev + prod, annotated YAML)
+   bin/export-bundler-config --doctor
+   # Creates: webpack-development-client.yaml, webpack-development-server.yaml,
+   #          webpack-production-client.yaml, webpack-production-server.yaml
+   ```
+
+   **Other usage examples:**
+
+   ```bash
+   # Save current environment configs with auto-generated names
+   bin/export-bundler-config --save
+   # Creates: webpack-development-client.yaml, webpack-development-server.yaml
+
+   # Save to specific directory
+   bin/export-bundler-config --save --save-dir=./debug-configs
+
+   # Export only client config for production
+   bin/export-bundler-config --save --env=production --client-only
+   # Creates: webpack-production-client.yaml
+
+   # Compare development vs production configs
+   bin/export-bundler-config --save --save-dir=./configs
+   diff configs/webpack-development-client.yaml configs/webpack-production-client.yaml
+
+   # View config in terminal (no files created)
+   bin/export-bundler-config
+
+   # Export without inline documentation annotations
+   bin/export-bundler-config --save --no-annotate
+
+   # Export in JSON format for programmatic analysis
+   bin/export-bundler-config --save --format=json
+   ```
+
+   **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)
+
+   See `bin/export-bundler-config --help` for all available options.
+
+6. Generate webpack stats for build analysis (useful for bundle size optimization):
+
+   ```bash
+   NODE_ENV=development bin/shakapacker --profile --json > /tmp/webpack-stats.json
+   ```
+
+   ChatGPT and other AI tools can consume this output file. Change the NODE_ENV per your needs.
+
 ## Incorrect peer dependencies
+
 Shakapacker uses peer dependencies to make it easier to manage what versions are being used for your app, which is especially
 useful for patching security vulnerabilities. However, not all package managers will actually enforce these versions - notably,
 Yarn will omit a warning rather than erroring if you forget to update a peer dependency:
@@ -27,6 +92,7 @@ warning " > shakapacker@6.1.1" has incorrect peer dependency "compression-webpac
 ```
 
 This omission resulted in an error in the browser:
+
 ```
 Failed to load resource: net::ERR_CONTENT_DECODING_FAILED
 ```
@@ -35,6 +101,40 @@ The error was caused by an old version of the peer dependency `webpack-compressi
 
 So, be sure to investigate warnings from `yarn install`!
 
+## NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+
+If you see this error during deployment (especially on Heroku with a staging environment):
+
+```
+NoMethodError: undefined method 'deep_symbolize_keys' for nil:NilClass
+  from shakapacker/configuration.rb:XXX:in 'load'
+```
+
+This happens when deploying to a custom Rails environment (like `staging`) that isn't explicitly defined in your `config/shakapacker.yml` file.
+
+**Solution:** This was fixed in Shakapacker v9.1.1+. Upgrade to the latest version:
+
+```ruby
+# Gemfile
+gem 'shakapacker', '~> 9.1'
+```
+
+After upgrading, Shakapacker will automatically fall back to sensible defaults when your environment isn't defined:
+
+1. First tries your environment (e.g., `staging`)
+2. Falls back to `production` configuration
+
+**Alternative:** If you can't upgrade immediately, explicitly add your environment to `config/shakapacker.yml`:
+
+```yaml
+staging:
+  <<: *default
+  compile: false
+  cache_manifest: true
+```
+
+See the [deployment guide](./deployment.md#custom-rails-environments-eg-staging) for more details.
+
 ## ENOENT: no such file or directory - node-sass
 
 If you get the error `ENOENT: no such file or directory - node-sass` on deploy with
@@ -49,7 +149,7 @@ thing, like Heroku.
 
 However, if you get this on local development, or not during a deploy then you
 may need to rebuild `node-sass`. It's a bit of a weird error; basically, it
-can't find the `node-sass` binary.  An easy solution is to create a postinstall
+can't find the `node-sass` binary. An easy solution is to create a postinstall
 hook to ensure `node-sass` is rebuilt whenever new modules are installed.
 
 In `package.json`:
@@ -62,19 +162,18 @@ In `package.json`:
 
 ## Can't find hello_react.js in manifest.json
 
-* If you get this error `Can't find hello_react.js in manifest.json`
-when loading a view in the browser it's because webpack is still compiling packs.
-Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
-however since this file is generated after packs are compiled by webpack. So,
-if you load a view in browser whilst webpack is compiling you will get this error.
-Therefore, make sure webpack
-(i.e `./bin/shakapacker-dev-server`) is running and has
-completed the compilation successfully before loading a view.
-
+- If you get this error `Can't find hello_react.js in manifest.json`
+  when loading a view in the browser it's because webpack is still compiling packs.
+  Shakapacker uses a `manifest.json` file to keep track of packs in all environments,
+  however since this file is generated after packs are compiled by webpack. So,
+  if you load a view in browser whilst webpack is compiling you will get this error.
+  Therefore, make sure webpack
+  (i.e `./bin/shakapacker-dev-server`) is running and has
+  completed the compilation successfully before loading a view.
 
 ## throw er; // Unhandled 'error' event
 
-* If you get this error while trying to use Elm, try rebuilding Elm. You can do
+- If you get this error while trying to use Elm, try rebuilding Elm. You can do
   so with a postinstall hook in your `package.json`:
 
 ```json
@@ -85,9 +184,9 @@ completed the compilation successfully before loading a view.
 
 ## webpack or webpack-dev-server not found
 
-* This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
+- This could happen if `shakapacker:install` step is skipped. Please run `bundle exec rails shakapacker:install` to fix the issue.
 
-* If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
+- If you encounter the above error on heroku after upgrading from Rails 4.x to 5.1.x, then the problem might be related to missing `yarn` binstub. Please run following commands to update/add binstubs:
 
 ```bash
 bundle config --delete bin
@@ -132,6 +231,7 @@ chmod +x $HOME/your_rails_app/node_modules/.bin/elm-make
 ```
 
 ## Rake assets:precompile fails. ExecJS::RuntimeError
+
 This error occurs because you are trying to minify by `terser` a pack that's already been minified by Shakapacker. To avoid this conflict and prevent appearing of `ExecJS::RuntimeError` error, you will need to disable uglifier from Rails config:
 
 ```ruby
@@ -147,10 +247,11 @@ Rails.application.config.assets.js_compressor = Uglifier.new(harmony: true)
 ### Angular: WARNING in ./node_modules/@angular/core/esm5/core.js, Critical dependency: the request of a dependency is an expression
 
 To silent these warnings, please update `config/webpack/webpack.config.js`:
+
 ```js
-const webpack = require('webpack')
-const { resolve } = require('path')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { resolve } = require("path")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
@@ -187,6 +288,7 @@ Thus ProvidePlugin manages build-time dependencies to global symbols whereas the
 **You don't need to assign dependencies on `window`.**
 
 For instance, with [jQuery](https://jquery.com/):
+
 ```diff
 // app/javascript/entrypoints/application.js
 
@@ -195,19 +297,20 @@ For instance, with [jQuery](https://jquery.com/):
 ```
 
 Instead do:
+
 ```js
 // config/webpack/webpack.config.js
 
-const webpack = require('webpack')
-const { generateWebpackConfig } = require('shakapacker')
+const webpack = require("webpack")
+const { generateWebpackConfig } = require("shakapacker")
 
 module.exports = generateWebpackConfig({
   plugins: [
     new webpack.ProvidePlugin({
-      $: 'jquery',
-      jQuery: 'jquery',
+      $: "jquery",
+      jQuery: "jquery"
     })
-  ],
+  ]
 })
 ```
 
@@ -220,7 +323,7 @@ application is using your staging `config.asset_host` host when using
 
 This can be fixed by setting the environment variable `SHAKAPACKER_ASSET_HOST` to
 an empty string where your assets are compiled. On Heroku this is done under
-*Settings* -> *Config Vars*.
+_Settings_ -> _Config Vars_.
 
 This way shakapacker won't hard-code the CDN host into the manifest file used by
 `javascript_pack_tag`, but instead fetch the CDN host at runtime, resolving the
@@ -228,3 +331,35 @@ issue.
 
 See [this issue](https://github.com/rails/webpacker/issues/3005) for more
 details.
+
+## Static file dependencies emitted outside of public output path
+
+For static file assets (images, fonts), we use [a Webpack rule](https://github.com/shakacode/shakapacker/blob/main/package/rules/file.js) to handle those files as `asset/resource` type and output them in the `static` folder in the public output path.
+
+In order to generate the storage path, we rely on the filename that's [provided by webpack internals](https://webpack.js.org/configuration/output/#outputfilename).
+
+This usually works out of the box. There's a potential problem however, if you use the [context setting](https://webpack.js.org/configuration/entry-context/#context) in your webpack config. By default this is set to current Node working directory/project root.
+
+If you were to override it like:
+
+```
+{
+  context: path.resolve(__dirname, '../../app/javascript')
+}
+```
+
+Then the filename available in the rule generator will be relative to that directory.
+
+This means for example:
+
+- a static asset from `node_modules` folder could end up being referenced with path of `../../node_modules/some_module/static_file.jpg` rather than simply `node_modules/some_module/static_file.jpg`.
+- a static asset in one of the `additional_paths`, example `app/assets/images/image.jpg`, would end up being referenced with path of `../assets/images/image.jpg`.
+
+Those paths are later passed to [output path generation in the rule](https://github.com/shakacode/shakapacker/blob/e52b335dbabfb934fe7d3076a8322b97d5ef3470/package/rules/file.js#L25-L26), where we would end up with a path like `static/../../node_modules/some_module/static_file.jpg`, resulting in the file being output in a location two directories above the desired path.
+
+You can avoid this by:
+
+- not using overridden `context` in your webpack config, if there's no good reason for it.
+- using custom Webpack config to modify the static file rule, following a similar process as outlined in the [Webpack Configuration](https://github.com/shakacode/shakapacker/blob/main/README.md#webpack-configuration) section of the readme.
+
+See [this issue](https://github.com/shakacode/shakapacker/issues/538) for more details.