shakapacker 9.1.0 → 9.3.0.beta.0

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

@@ -0,0 +1,195 @@
+# Releasing Shakapacker
+
+This guide is for Shakapacker maintainers who need to publish a new release.
+
+## Prerequisites
+
+1. **Install required tools:**
+
+   ```bash
+   bundle install              # Installs gem-release
+   yarn global add release-it  # Installs release-it for npm publishing
+   ```
+
+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)
+
+3. **Enable 2FA on both platforms:**
+   - npm: 2FA is required for publishing
+   - RubyGems: 2FA is required for publishing
+
+## Release Process
+
+### 1. Prepare the Release
+
+Before running the release task:
+
+1. Ensure all desired changes are merged to `main` branch
+2. Update `CHANGELOG.md` with the new version and release notes
+3. Commit the CHANGELOG changes
+4. Ensure your working directory is clean (`git status` shows no uncommitted changes)
+
+### 2. Run the Release Task
+
+The automated release task handles the entire release process:
+
+```bash
+# For a specific version (e.g., 9.1.0)
+rake create_release[9.1.0]
+
+# For a beta release (note: use period, not dash)
+rake create_release[9.2.0.beta.1]  # Creates npm package 9.2.0-beta.1
+
+# For a patch version bump (auto-increments)
+rake create_release
+
+# Dry run to test without publishing
+rake create_release[9.1.0,true]
+```
+
+### 3. What the Release Task Does
+
+The `create_release` task automatically:
+
+1. **Pulls latest changes** from the repository
+2. **Bumps version numbers** in:
+   - `lib/shakapacker/version.rb` (Ruby gem version)
+   - `package.json` (npm package version - converted from Ruby format)
+3. **Publishes to npm:**
+   - Prompts for npm OTP (2FA code)
+   - Creates git tag
+   - Pushes to GitHub
+4. **Publishes to RubyGems:**
+   - Prompts for RubyGems OTP (2FA code)
+5. **Updates spec/dummy lockfiles:**
+   - Runs `bundle install` to update `Gemfile.lock`
+   - Runs `npm install` to update `package-lock.json` (yarn.lock may also be updated for multi-package-manager compatibility testing)
+6. **Commits and pushes lockfile changes** automatically
+
+### 4. Version Format
+
+**Important:** Use Ruby gem version format (no dashes):
+
+- ✅ Correct: `9.1.0`, `9.2.0.beta.1`, `9.0.0.rc.2`
+- ❌ Wrong: `9.1.0-beta.1`, `9.0.0-rc.2`
+
+The task automatically converts Ruby gem format to npm semver format:
+
+- Ruby: `9.2.0.beta.1` → npm: `9.2.0-beta.1`
+- Ruby: `9.0.0.rc.2` → npm: `9.0.0-rc.2`
+
+**Examples:**
+
+```bash
+# Regular release
+rake create_release[9.1.0]  # Gem: 9.1.0, npm: 9.1.0
+
+# Beta release
+rake create_release[9.2.0.beta.1]  # Gem: 9.2.0.beta.1, npm: 9.2.0-beta.1
+
+# Release candidate
+rake create_release[10.0.0.rc.1]  # Gem: 10.0.0.rc.1, npm: 10.0.0-rc.1
+```
+
+### 5. During the Release
+
+1. When prompted for **npm OTP**, enter your 2FA code from your authenticator app
+2. Accept defaults for release-it options
+3. When prompted for **RubyGems OTP**, enter your 2FA code
+4. The script will automatically commit and push lockfile updates
+
+### 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)
+
+2. Check that the lockfile commit was pushed:
+
+   ```bash
+   git log --oneline -5
+   # Should see "Update spec/dummy lockfiles after release"
+   ```
+
+3. Announce the release (if appropriate):
+   - Post in relevant Slack/Discord channels
+   - Tweet about major releases
+   - Update documentation if needed
+
+## Troubleshooting
+
+### Uncommitted Changes After Release
+
+If you see uncommitted changes to lockfiles after a release, this means:
+
+1. The release was successful but the lockfile commit step may have failed
+2. **Solution:** Manually commit these files:
+   ```bash
+   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
+   git commit -m 'Update spec/dummy lockfiles after release'
+   git push
+   ```
+
+### Failed npm or RubyGems Publish
+
+If publishing fails partway through:
+
+1. Check which step failed (npm or RubyGems)
+2. If npm failed: Fix the issue and manually run `npm publish`
+3. If RubyGems failed: Fix the issue and manually run `gem release`
+4. Then manually update and commit spec/dummy lockfiles
+
+### Wrong Version Format
+
+If you accidentally use npm format (with dashes):
+
+1. The gem will be created with an invalid version
+2. **Solution:** Don't push the changes, reset your branch:
+   ```bash
+   git reset --hard HEAD
+   ```
+3. Re-run with correct Ruby gem format
+
+## Manual Release Steps
+
+If you need to release manually (not recommended):
+
+1. **Bump version:**
+
+   ```bash
+   gem bump --version 9.1.0
+   bundle install
+   ```
+
+2. **Publish to npm:**
+
+   ```bash
+   release-it 9.1.0 --npm.publish
+   ```
+
+3. **Publish to RubyGems:**
+
+   ```bash
+   gem release
+   ```
+
+4. **Update lockfiles:**
+   ```bash
+   cd spec/dummy
+   bundle install
+   npm install
+   cd ../..
+   git add spec/dummy/Gemfile.lock spec/dummy/package-lock.json spec/dummy/yarn.lock
+   git commit -m 'Update spec/dummy lockfiles after release'
+   git push
+   ```
+
+## Questions?
+
+If you encounter issues not covered here, please:
+
+1. Check the [CONTRIBUTING.md](../CONTRIBUTING.md) guide
+2. Ask in the maintainers channel
+3. Update this documentation for future releases

data/docs/rspack.md

@@ -2,6 +2,8 @@
 
 Shakapacker supports [Rspack](https://rspack.rs) as an alternative assets bundler to Webpack. Rspack is a fast Rust-based web bundler with webpack-compatible API that can significantly speed up your build times.
 
+**📖 For configuration options, see the [Configuration Guide](./configuration.md)**
+
 ## Installation
 
 First, install the required Rspack dependencies:
@@ -10,7 +12,7 @@ First, install the required Rspack dependencies:
 npm install @rspack/core @rspack/cli -D
 # or
 yarn add @rspack/core @rspack/cli -D
-# or  
+# or
 pnpm add @rspack/core @rspack/cli -D
 # or
 bun add @rspack/core @rspack/cli -D
@@ -23,9 +25,8 @@ Note: These packages are already listed as optional peer dependencies in Shakapa
 To enable Rspack, update your `config/shakapacker.yml`:
 
 ```yaml
-default: &default
-  # ... other config options
-  assets_bundler: 'rspack'  # Change from 'webpack' to 'rspack'
+default: &default # ... other config options
+  assets_bundler: "rspack" # Change from 'webpack' to 'rspack'
 ```
 
 ### Configuration Files
@@ -33,7 +34,7 @@ default: &default
 Rspack uses its own configuration directory to keep things organized. Create your Rspack configuration file at `config/rspack/rspack.config.js`:
 
 ```javascript
-const { generateRspackConfig } = require('shakapacker/rspack')
+const { generateRspackConfig } = require("shakapacker/rspack")
 
 module.exports = generateRspackConfig()
 ```
@@ -43,14 +44,12 @@ module.exports = generateRspackConfig()
 If you need to customize your Rspack configuration:
 
 ```javascript
-const { generateRspackConfig } = require('shakapacker/rspack')
+const { generateRspackConfig } = require("shakapacker/rspack")
 
 const rspackConfig = generateRspackConfig({
-  plugins: [
-    new SomeRspackCompatiblePlugin()
-  ],
+  plugins: [new SomeRspackCompatiblePlugin()],
   resolve: {
-    extensions: ['.ts', '.tsx', '.js', '.jsx']
+    extensions: [".ts", ".tsx", ".js", ".jsx"]
   }
 })
 
@@ -62,14 +61,16 @@ module.exports = rspackConfig
 If you have an existing `config/webpack/webpack.config.js`, you can migrate it to `config/rspack/rspack.config.js`:
 
 **Old (webpack.config.js):**
+
 ```javascript
-const { generateWebpackConfig } = require('shakapacker')
+const { generateWebpackConfig } = require("shakapacker")
 module.exports = generateWebpackConfig()
 ```
 
 **New (rspack.config.js):**
+
 ```javascript
-const { generateRspackConfig } = require('shakapacker/rspack')
+const { generateRspackConfig } = require("shakapacker/rspack")
 module.exports = generateRspackConfig()
 ```
 
@@ -89,11 +90,11 @@ Rspack has built-in loaders that are faster than their webpack counterparts:
 
 Most webpack plugins work with Rspack, but some have Rspack-specific alternatives:
 
-| Webpack Plugin | Rspack Alternative | Status |
-|---|---|---|
-| `mini-css-extract-plugin` | `rspack.CssExtractRspackPlugin` | Built-in |
-| `copy-webpack-plugin` | `rspack.CopyRspackPlugin` | Built-in |
-| `terser-webpack-plugin` | `rspack.SwcJsMinimizerRspackPlugin` | Built-in |
+| Webpack Plugin            | Rspack Alternative                  | Status   |
+| ------------------------- | ----------------------------------- | -------- |
+| `mini-css-extract-plugin` | `rspack.CssExtractRspackPlugin`     | Built-in |
+| `copy-webpack-plugin`     | `rspack.CopyRspackPlugin`           | Built-in |
+| `terser-webpack-plugin`   | `rspack.SwcJsMinimizerRspackPlugin` | Built-in |
 
 ### Minification
 
@@ -136,28 +137,31 @@ The same dev server configuration in `shakapacker.yml` applies to both webpack a
 Rspack typically provides:
 
 - **2-10x faster** cold builds
-- **5-20x faster** incremental builds  
+- **5-20x faster** incremental builds
 - **Faster HMR** (Hot Module Replacement)
 - **Lower memory usage**
 
 ## Migration Checklist
 
 1. **Install Rspack dependencies:**
+
    ```bash
    npm install @rspack/core @rspack/cli -D
    ```
 
 2. **Update configuration:**
+
    ```yaml
    # config/shakapacker.yml
    default: &default
-     assets_bundler: 'rspack'
+     assets_bundler: "rspack"
    ```
 
 3. **Create Rspack config:**
+
    ```javascript
    // config/rspack/rspack.config.js
-   const { generateRspackConfig } = require('shakapacker/rspack')
+   const { generateRspackConfig } = require("shakapacker/rspack")
    module.exports = generateRspackConfig()
    ```
 
@@ -187,4 +191,4 @@ If builds are unexpectedly slow:
 
 - [Rspack Official Documentation](https://rspack.rs)
 - [Rspack Migration Guide](https://rspack.rs/guide/migration/webpack)
-- [Rspack Plugins](https://rspack.rs/plugins/webpack/)
+- [Rspack Plugins](https://rspack.rs/plugins/webpack/)