shakapacker 9.2.0 → 9.3.0.beta.0

data/docs/peer-dependencies.md

@@ -1,4 +1,5 @@
 # Shakapacker's Peer Dependencies
+
 ## Last updated for our 9.0.0 version — see lib/install/package.json
 
 To simplify peer dependencies while supporting both webpack & rspack, we decided to document the dependencies here instead of creating two separate npm packages.
@@ -6,13 +7,16 @@ To simplify peer dependencies while supporting both webpack & rspack, we decided
 **Important Note**: Starting with v9, Babel dependencies are no longer included as peer dependencies. They will be installed automatically only if you're using Babel as your JavaScript transpiler.
 
 ## Essential for Rspack
-```
+
+```text
     "@rspack/cli": "^1.0.0",
     "@rspack/core": "^1.0.0",
     "rspack-manifest-plugin": "^5.0.0",
 ```
+
 ## Essential for Webpack
-```
+
+```text
     "mini-css-extract-plugin": "^2.0.0",
     "terser-webpack-plugin": "^5.3.1",
     "webpack": "^5.76.0",
@@ -24,7 +28,8 @@ To simplify peer dependencies while supporting both webpack & rspack, we decided
 ```
 
 ## Highly recommended
-```
+
+```text
     "compression-webpack-plugin": "^9.0.0 || ^10.0.0|| ^11.0.0",
     "css-loader": "^6.0.0 || ^7.0.0",
     "sass-loader": "^13.0.0 || ^14.0.0 || ^15.0.0 || ^16.0.0",
@@ -34,27 +39,33 @@ To simplify peer dependencies while supporting both webpack & rspack, we decided
 ## Optional JavaScript Transpilers
 
 ### Babel (installed automatically when `javascript_transpiler: 'babel'`)
-```
+
+```text
     "@babel/core": "^7.17.9",
     "@babel/plugin-transform-runtime": "^7.17.0",
     "@babel/preset-env": "^7.16.11",
     "@babel/runtime": "^7.17.9",
     "babel-loader": "^8.2.4 || ^9.0.0 || ^10.0.0",
 ```
+
 Note: These dependencies are only installed if you're using Babel as your JavaScript transpiler. Consider using SWC or esbuild for better performance.
 
 ### SWC (default - 20x faster than Babel)
-```
+
+```text
     "@swc/core": "latest",
     "swc-loader": "latest"
 ```
+
 - **For webpack**: Installed automatically when using default configuration
 - **For rspack**: Built-in, no additional installation needed (rspack includes SWC natively)
 - Manual install: `npm install @swc/core swc-loader`
 
 ### esbuild
-```
+
+```text
     "esbuild": "latest",
     "esbuild-loader": "latest"
 ```
+
 Install manually with: `npm install esbuild esbuild-loader`

data/docs/precompile_hook.md

@@ -0,0 +1,342 @@
+# Precompile Hook
+
+The `precompile_hook` configuration option allows you to run a custom command before asset compilation.
+
+**📖 For other configuration options, see the [Configuration Guide](./configuration.md)**
+
+This is useful for:
+
+- Dynamically generating entry points (e.g., from database records)
+- Running preparatory tasks before bundling
+- Integrating with tools like React on Rails that need to generate packs
+
+## When to Use
+
+The precompile hook is especially useful when you need to run commands like:
+
+- `bin/rails react_on_rails:generate_packs` - Generate dynamic entry points
+- `bin/rails react_on_rails:locale` - Generate locale files
+- Any custom script that prepares files before asset compilation
+
+**Important:** The hook runs in **both development and production**:
+
+- **Development**: Runs before `bin/shakapacker --watch` or dev server starts
+- **Production**: Runs before `rails assets:precompile`
+
+## Configuration
+
+Add the `precompile_hook` option to your `config/shakapacker.yml`:
+
+```yaml
+# For all environments
+default: &default
+  precompile_hook: "bin/shakapacker-precompile-hook"
+
+# Or environment-specific
+development:
+  <<: *default
+  precompile_hook: "bin/dev-setup"
+
+production:
+  <<: *default
+  precompile_hook: "bin/rails react_on_rails:generate_packs"
+```
+
+## Creating a Precompile Hook Script
+
+### Simple Shell Script
+
+```bash
+#!/usr/bin/env bash
+# bin/shakapacker-precompile-hook
+
+echo "Preparing assets..."
+bin/rails react_on_rails:generate_packs
+bin/rails react_on_rails:locale
+echo "Assets prepared successfully"
+```
+
+### Ruby Script with Database Access
+
+```ruby
+#!/usr/bin/env ruby
+# bin/shakapacker-precompile-hook
+
+require_relative "../config/environment"
+
+puts "Generating dynamic entry points..."
+
+# Generate entry points from database
+Theme.find_each do |theme|
+  entry_point = Rails.root.join("app/javascript/packs/theme_#{theme.id}.js")
+  File.write(entry_point, "import '../themes/#{theme.identifier}';")
+  puts "  Created #{entry_point}"
+end
+
+puts "Entry points generated successfully"
+exit 0
+```
+
+Make the script executable:
+
+```bash
+chmod +x bin/shakapacker-precompile-hook
+```
+
+## How It Works
+
+### Execution Flow
+
+1. **Triggered** when asset compilation starts
+2. **Hook runs** in your project root directory
+3. **Environment variables** are passed through (including `NODE_ENV`, `RAILS_ENV`, `SHAKAPACKER_ASSET_HOST`)
+4. **On success** (exit code 0): Compilation proceeds
+5. **On failure** (non-zero exit code): Compilation stops with error
+
+**Migration Note:** If you're migrating from custom `assets:precompile` enhancements (e.g., in `lib/tasks/assets.rake`), ensure you don't run the same commands twice. React on Rails versions before 16.1.1 automatically prepend `react_on_rails:generate_packs` to `assets:precompile`. Versions 16.1.1+ detect `precompile_hook` and skip automatic task enhancement to avoid duplicate execution. For custom Rake task enhancements, remove manual invocations when adding `precompile_hook`.
+
+To verify correct migration, run `rake assets:precompile` and check the logs. Commands like `react_on_rails:generate_packs` should appear **only once** in the output. If you see duplicate execution, either upgrade React on Rails to 16.1.1+ or remove your custom task enhancements.
+
+### Logging
+
+The hook's stdout and stderr are logged:
+
+```
+Running precompile hook: bin/shakapacker-precompile-hook
+Preparing assets...
+Entry points generated successfully
+Precompile hook completed successfully
+Compiling...
+```
+
+## React on Rails Integration
+
+For React on Rails projects, the hook replaces manual steps in your workflow:
+
+### Before (Manual)
+
+```bash
+# Development
+bin/rails react_on_rails:generate_packs
+bin/rails react_on_rails:locale
+bin/shakapacker-dev-server
+
+# Production
+bin/rails react_on_rails:generate_packs
+bin/rails react_on_rails:locale
+RAILS_ENV=production bin/rails assets:precompile
+```
+
+### After (Automatic)
+
+```yaml
+# config/shakapacker.yml
+default: &default
+  precompile_hook: "bin/react-on-rails-hook"
+```
+
+```bash
+#!/usr/bin/env bash
+# bin/react-on-rails-hook
+bin/rails react_on_rails:generate_packs
+bin/rails react_on_rails:locale
+```
+
+Now simply run:
+
+```bash
+# Development
+bin/shakapacker-dev-server
+
+# Production
+RAILS_ENV=production bin/rails assets:precompile
+```
+
+## Security
+
+For security reasons, the precompile hook is validated to ensure:
+
+### 1. Project Root Restriction
+
+The hook **must** reference a script within your project root:
+
+```yaml
+# ✅ Valid - within project
+precompile_hook: 'bin/shakapacker-precompile-hook'
+precompile_hook: 'script/prepare-assets'
+precompile_hook: 'bin/hook --arg1 --arg2'
+
+# ❌ Invalid - outside project
+precompile_hook: '/usr/bin/malicious-script'
+precompile_hook: '../../../etc/passwd'
+```
+
+### 2. Symlink Resolution
+
+Symlinks are resolved to their real paths before validation:
+
+```bash
+# If bin/hook is a symlink to /usr/bin/evil
+# The validation will detect and reject it
+```
+
+### 3. Path Traversal Protection
+
+Path traversal attempts are blocked:
+
+```yaml
+# ❌ These will be rejected
+precompile_hook: 'bin/../../etc/passwd'
+precompile_hook: '../outside-project/script'
+```
+
+### 4. Proper Path Boundary Checking
+
+Partial path matches are prevented:
+
+```
+# /project won't match /project-evil
+# Uses File::SEPARATOR for proper validation
+```
+
+## Error Handling
+
+### Hook Failure
+
+If the hook fails, you'll see a detailed error:
+
+```
+PRECOMPILE HOOK FAILED:
+EXIT STATUS: 1
+COMMAND: bin/shakapacker-precompile-hook
+OUTPUTS:
+Error: Theme not found
+
+To fix this:
+  1. Check that the hook script exists and is executable
+  2. Test the hook command manually: bin/shakapacker-precompile-hook
+  3. Review the error output above for details
+  4. You can disable the hook temporarily by commenting out 'precompile_hook' in shakapacker.yml
+```
+
+### Missing Executable
+
+If the script doesn't exist, you'll see a warning:
+
+```
+⚠️  Warning: precompile_hook executable not found: /path/to/project/bin/hook
+   The hook command is configured but the script does not exist within the project root.
+   Please ensure the script exists or remove 'precompile_hook' from your shakapacker.yml configuration.
+```
+
+## Troubleshooting
+
+### Test the Hook Manually
+
+Run the hook directly to see what happens:
+
+```bash
+bin/shakapacker-precompile-hook
+echo $?  # Should output 0 for success
+```
+
+### Check Permissions
+
+Ensure the script is executable:
+
+```bash
+ls -la bin/shakapacker-precompile-hook
+# Should show: -rwxr-xr-x (executable)
+
+# If not executable:
+chmod +x bin/shakapacker-precompile-hook
+```
+
+### Debug with Verbose Output
+
+Add debug output to your hook:
+
+```bash
+#!/usr/bin/env bash
+set -x  # Enable verbose mode
+echo "Current directory: $(pwd)"
+echo "Environment: $RAILS_ENV"
+# Your commands here
+```
+
+### Temporarily Disable
+
+To disable the hook for testing:
+
+```yaml
+# config/shakapacker.yml
+default:
+  # precompile_hook: 'bin/shakapacker-precompile-hook'
+```
+
+### Common Issues
+
+**Issue:** Hook fails in production but works in development - Verify all dependencies are available (database, commands, gems)
+
+**Issue:** Generated files not found - Check `source_path` and `source_entry_path` in `shakapacker.yml`
+
+**Issue:** Permission denied - Run `chmod +x bin/shakapacker-precompile-hook`
+
+## Advanced Usage
+
+### Conditional Execution
+
+```bash
+#!/usr/bin/env bash
+# bin/shakapacker-precompile-hook
+
+if [ "$RAILS_ENV" = "production" ]; then
+  echo "Running production-specific setup..."
+  bin/rails react_on_rails:generate_packs
+else
+  echo "Running development setup..."
+  # Lighter-weight setup for development
+fi
+```
+
+### Hook with Arguments
+
+```yaml
+precompile_hook: "bin/prepare-assets --verbose --cache-bust"
+```
+
+```bash
+#!/usr/bin/env bash
+# bin/prepare-assets
+
+VERBOSE=false
+CACHE_BUST=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --verbose) VERBOSE=true ;;
+    --cache-bust) CACHE_BUST=true ;;
+  esac
+  shift
+done
+
+if [ "$VERBOSE" = true ]; then
+  echo "Preparing assets..."
+fi
+```
+
+### Handling Spaces in Paths
+
+Use quotes for paths with spaces:
+
+```yaml
+precompile_hook: "'bin/my hook script' --arg1"
+```
+
+The hook system uses `Shellwords` to properly parse quoted arguments.
+
+## See Also
+
+- [Deployment Guide](deployment.md) - Production deployment considerations
+- [React on Rails Integration](https://github.com/shakacode/react_on_rails) - Main use case documentation
+- [Configuration](../README.md#configuration-and-code) - General shakapacker configuration

data/docs/react.md

@@ -53,19 +53,17 @@ npm install --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
 Alter `config/webpack/webpack.config.js` like so:
 
 ```js
-const { generateWebpackConfig, inliningCss } = require('shakapacker');
-const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
-const isDevelopment = process.env.NODE_ENV !== 'production';
+const { generateWebpackConfig, inliningCss } = require("shakapacker")
+const ReactRefreshWebpackPlugin = require("@pmmmwh/react-refresh-webpack-plugin")
+const isDevelopment = process.env.NODE_ENV !== "production"
 
-const webpackConfig = generateWebpackConfig();
+const webpackConfig = generateWebpackConfig()
 
 if (isDevelopment && inliningCss) {
-  webpackConfig.plugins.push(
-    new ReactRefreshWebpackPlugin()
-  );
+  webpackConfig.plugins.push(new ReactRefreshWebpackPlugin())
 }
 
-module.exports = webpackConfig;
+module.exports = webpackConfig
 ```
 
 This applies the plugin to the webpack configuration.
@@ -85,16 +83,16 @@ Then create a `babel.config.js` file in the root of project and add the followin
 
 ```js
 module.exports = function (api) {
-  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const defaultConfigFunc = require("shakapacker/package/babel/preset.js")
   const resultConfig = defaultConfigFunc(api)
-  const isDevelopmentEnv = api.env('development')
-  const isProductionEnv = api.env('production')
-  const isTestEnv = api.env('test')
+  const isDevelopmentEnv = api.env("development")
+  const isProductionEnv = api.env("production")
+  const isTestEnv = api.env("test")
 
   const changesOnDefault = {
     presets: [
       [
-        '@babel/preset-react',
+        "@babel/preset-react",
         {
           development: isDevelopmentEnv || isTestEnv,
           useBuiltIns: true
@@ -102,17 +100,18 @@ module.exports = function (api) {
       ]
     ].filter(Boolean),
     plugins: [
-      isProductionEnv && ['babel-plugin-transform-react-remove-prop-types',
+      isProductionEnv && [
+        "babel-plugin-transform-react-remove-prop-types",
         {
           removeImport: true
         }
       ],
-      process.env.WEBPACK_SERVE && 'react-refresh/babel'
-    ].filter(Boolean),
+      process.env.WEBPACK_SERVE && "react-refresh/babel"
+    ].filter(Boolean)
   }
 
   resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
-  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins ]
+  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins]
 
   return resultConfig
 }
@@ -127,6 +126,7 @@ HMR for your React app is now enabled. 🚀
 To test that all of the above is working, you can follow these instructions to create a basic React app using Shakapacker.
 
 1. Create a new Rails app:
+
 ```shell
 rails new myapp --skip-javascript
 cd myapp
@@ -138,44 +138,52 @@ npm install css-loader style-loader mini-css-extract-plugin css-minimizer-webpac
 ```
 
 2. Generate a controller
+
 ```shell
 rails g controller site index
 echo '<div id="root"></div>' > app/views/site/index.html.erb
 ```
 
 3. Create a CSS file and a React component:
+
 ```shell
 touch app/javascript/App.css app/javascript/App.js
 ```
 
 4. Edit `app/javascript/packs/application.js` like so:
+
 ```jsx
-import React from 'react';
-import { createRoot } from 'react-dom/client';
-import HelloMessage from '../App';
+import React from "react"
+import { createRoot } from "react-dom/client"
+import HelloMessage from "../App"
 
-const container = document.getElementById('root');
-const root = createRoot(container);
+const container = document.getElementById("root")
+const root = createRoot(container)
 
-document.addEventListener('DOMContentLoaded', () => {
-  root.render(<HelloMessage name="World" />);
-});
+document.addEventListener("DOMContentLoaded", () => {
+  root.render(<HelloMessage name="World" />)
+})
 ```
 
 5. Add the following to `app/javascript/App.js`:
+
 ```jsx
-import React from 'react';
-import 'App.css';
-const HelloMessage = ({ name }) => <h1>Hello, {name}!</h1>;
-export default HelloMessage;
+import React from "react"
+import "App.css"
+const HelloMessage = ({ name }) => <h1>Hello, {name}!</h1>
+export default HelloMessage
 ```
 
 6. Add the following to `app/javascript/App.css`:
+
 ```css
-h1 { color: blue; }
+h1 {
+  color: blue;
+}
 ```
 
 7. Enable HMR in config/shakapacker.yml:
+
 ```shell
 hmr: true
 ```
@@ -189,22 +197,21 @@ npm install --dev react-refresh @pmmmwh/react-refresh-webpack-plugin
 9. Alter `config/webpack/webpack.config.js` like so:
 
 ```js
-const { generateWebpackConfig, inliningCss } = require('shakapacker');
-const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
-const isDevelopment = process.env.NODE_ENV !== 'production';
+const { generateWebpackConfig, inliningCss } = require("shakapacker")
+const ReactRefreshWebpackPlugin = require("@pmmmwh/react-refresh-webpack-plugin")
+const isDevelopment = process.env.NODE_ENV !== "production"
 
-const webpackConfig = generateWebpackConfig();
+const webpackConfig = generateWebpackConfig()
 
 if (isDevelopment && inliningCss) {
-  webpackConfig.plugins.push(
-    new ReactRefreshWebpackPlugin()
-  );
+  webpackConfig.plugins.push(new ReactRefreshWebpackPlugin())
 }
 
-module.exports = webpackConfig;
+module.exports = webpackConfig
 ```
 
 10. Remove the Babel configuration from `package.json`
+
 ```diff
 - "babel": {
 -   "presets": [
@@ -214,18 +221,19 @@ module.exports = webpackConfig;
 ```
 
 11. Create a `babel.config.js` file in the project root and add the following [sample code](https://github.com/shakacode/shakapacker/blob/main/docs/customizing_babel_config.md#react-configuration):
+
 ```js
 module.exports = function (api) {
-  const defaultConfigFunc = require('shakapacker/package/babel/preset.js')
+  const defaultConfigFunc = require("shakapacker/package/babel/preset.js")
   const resultConfig = defaultConfigFunc(api)
-  const isDevelopmentEnv = api.env('development')
-  const isProductionEnv = api.env('production')
-  const isTestEnv = api.env('test')
+  const isDevelopmentEnv = api.env("development")
+  const isProductionEnv = api.env("production")
+  const isTestEnv = api.env("test")
 
   const changesOnDefault = {
     presets: [
       [
-        '@babel/preset-react',
+        "@babel/preset-react",
         {
           development: isDevelopmentEnv || isTestEnv,
           useBuiltIns: true
@@ -233,23 +241,25 @@ module.exports = function (api) {
       ]
     ].filter(Boolean),
     plugins: [
-      isProductionEnv && ['babel-plugin-transform-react-remove-prop-types',
+      isProductionEnv && [
+        "babel-plugin-transform-react-remove-prop-types",
         {
           removeImport: true
         }
       ],
-      process.env.WEBPACK_SERVE && 'react-refresh/babel'
-    ].filter(Boolean),
+      process.env.WEBPACK_SERVE && "react-refresh/babel"
+    ].filter(Boolean)
   }
 
   resultConfig.presets = [...resultConfig.presets, ...changesOnDefault.presets]
-  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins ]
+  resultConfig.plugins = [...resultConfig.plugins, ...changesOnDefault.plugins]
 
   return resultConfig
 }
 ```
 
 9. Start the Rails server and the `shakapacker-dev-server` in separate console windows:
+
 ```shell
 rails s
 ./bin/shakapacker-dev-server

data/docs/releasing.md

@@ -12,7 +12,6 @@ This guide is for Shakapacker maintainers who need to publish a new release.
    ```
 
 2. **Ensure you have publishing access:**
-
    - npm: You must be a collaborator on the [shakapacker npm package](https://www.npmjs.com/package/shakapacker)
    - RubyGems: You must be an owner of the [shakapacker gem](https://rubygems.org/gems/shakapacker)
 
@@ -103,7 +102,6 @@ rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
 ### 6. After Release
 
 1. Verify the release on:
-
    - [npm](https://www.npmjs.com/package/shakapacker)
    - [RubyGems](https://rubygems.org/gems/shakapacker)
    - [GitHub releases](https://github.com/shakacode/shakapacker/releases)