### Development Dependencies Setup

Source: https://github.com/shakacode/shakapacker/blob/main/CONTRIBUTING.md

Run `bin/setup` to install necessary development dependencies. Optionally, enable local pre-commit hooks with `npx husky`.

```bash
bin/setup
# Optional: enable local pre-commit hooks
npx husky
```

--------------------------------

### Install React and ReactDOM

Source: https://github.com/shakacode/shakapacker/blob/main/docs/react.md

Install the necessary React libraries using npm for basic manual setup.

```shell
npm install react react-dom
```

--------------------------------

### Manual Development Dependencies Setup

Source: https://github.com/shakacode/shakapacker/blob/main/CONTRIBUTING.md

Manually install development dependencies using `bundle install` and `yarn install`.

```bash
bundle install
yarn install
```

--------------------------------

### Install esbuild and esbuild-loader

Source: https://github.com/shakacode/shakapacker/blob/main/docs/using_esbuild_loader.md

Install the necessary packages for esbuild transpilation.

```bash
npm install esbuild esbuild-loader
```

--------------------------------

### Quick Start: Using RSpack

Source: https://github.com/shakacode/shakapacker/blob/main/spec/dummy/README.md

Commands to switch to RSpack, run the bundler, and start the development server.

```bash
# Switch to RSpack configuration
bin/test-bundler rspack

# Run the bundler
bin/shakapacker

# Start dev server
bin/shakapacker-dev-server
```

--------------------------------

### Quick Start: Using Webpack (Default)

Source: https://github.com/shakacode/shakapacker/blob/main/spec/dummy/README.md

Commands to run Shakapacker with Webpack, including starting the development server.

```bash
bin/shakapacker

# Or explicitly switch to webpack
bin/test-bundler webpack
bin/shakapacker

# Start dev server
bin/shakapacker-dev-server
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

After preparing Yarn, install project dependencies. This will create a yarn.lock file.

```bash
yarn install
```

--------------------------------

### Example Production Shakapacker Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/cdn_setup.md

A complete example of shakapacker.yml for a production setup, including CDN asset host, integrity checking, and CloudFlare considerations.

```yaml
# config/shakapacker.yml
production:
  compile: false
  cache_manifest: true
  asset_host: <%= ENV.fetch('SHAKAPACKER_ASSET_HOST', 'https://cdn.example.com') %>

  # Enable integrity checking
  integrity:
    enabled: true
    hash_functions: ["sha384"]
    cross_origin: "anonymous"

```

--------------------------------

### Manual Installer Testing Steps

Source: https://github.com/shakacode/shakapacker/blob/main/CONTRIBUTING.md

Manually test the Shakapacker installer by updating the `Gemfile`, running `bundle install`, and then executing `bundle exec rails shakapacker:install`.

```ruby
gem 'shakapacker', path: "relative_or_absolute_path_to_the_gem"
```

```bash
bundle install
bundle exec rails shakapacker:install
```

--------------------------------

### Start Rails and Shakapacker Dev Server

Source: https://github.com/shakacode/shakapacker/blob/main/docs/react.md

For the basic manual setup, run the Rails server and the Shakapacker development server in separate terminal windows.

```shell
rails s
./bin/shakapacker-dev-server
```

--------------------------------

### Install Stylus Loader Package

Source: https://github.com/shakacode/shakapacker/blob/main/docs/node_package_api.md

Install the `stylus` and `stylus-loader` packages for Stylus support.

```bash
npm install stylus stylus-loader
```

--------------------------------

### Install PostCSS Packages

Source: https://github.com/shakacode/shakapacker/blob/main/docs/node_package_api.md

Install PostCSS and related packages for CSS processing.

```bash
npm install postcss postcss-loader
```

```bash
npm install postcss-preset-env postcss-flexbugs-fixes
```

--------------------------------

### Example Shakapacker Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/configuration.md

A default configuration example for `config/shakapacker.yml`, illustrating `source_path`, `source_entry_path`, `public_root_path`, `public_output_path`, and `nested_entries`.

```yaml
default: &default
  source_path: app/javascript
  source_entry_path: packs
  public_root_path: public
  public_output_path: packs
  nested_entries: false
```

--------------------------------

### Install Release Tools

Source: https://github.com/shakacode/shakapacker/blob/main/docs/releasing.md

Installs necessary tools for releasing, including bundler, gem-release, and checks for npm and GitHub CLI versions.

```bash
bundle install
gem install gem-release     # Provides `gem bump` and `gem release`
npm --version               # Required because release task uses `npx release-it`
gh --version                # Required for automatic GitHub release creation
```

--------------------------------

### Run Installation Tests

Source: https://github.com/shakacode/shakapacker/blob/main/docs/optional-peer-dependencies.md

Execute the provided shell script to test for peer dependency warnings during installation. This script is located at test/peer-dependencies.sh.

```bash
# Test script available at test/peer-dependencies.sh
./test/peer-dependencies.sh
```

--------------------------------

### Precompile Hook Logging Example

Source: https://github.com/shakacode/shakapacker/blob/main/docs/precompile_hook.md

Example output demonstrating how the precompile hook's stdout and stderr are logged during the asset compilation process.

```text
Running precompile hook: bin/shakapacker-precompile-hook
Preparing assets...
Entry points generated successfully
Precompile hook completed successfully
Compiling...
```

--------------------------------

### Install SWC Dependencies

Source: https://github.com/shakacode/shakapacker/blob/main/docs/transpiler-migration.md

Install the necessary SWC core and loader packages as development dependencies.

```bash
yarn add --dev @swc/core swc-loader
```

--------------------------------

### Install Yarn Globally

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

An alternative method to install Yarn globally using npm.

```bash
npm install -g yarn
```

--------------------------------

### Install pnpm Globally

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

An alternative method to install pnpm globally using npm.

```bash
npm install -g pnpm
```

--------------------------------

### Install jscodeshift

Source: https://github.com/shakacode/shakapacker/blob/main/tools/README.md

Install the jscodeshift CLI globally to use the codemod.

```bash
npm install -g jscodeshift
```

--------------------------------

### Bump Version and Install Dependencies

Source: https://github.com/shakacode/shakapacker/blob/main/docs/releasing.md

Manually bump the version of the gem and install dependencies before proceeding with the release.

```bash
gem bump --version 10.1.0
bundle install
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/shakacode/shakapacker/blob/main/CONTRIBUTING.md

Installs project dependencies using Yarn. This command is typically run after setting up the Node.js environment in CI.

```bash
yarn install
```

--------------------------------

### Verify Shakapacker Install

Source: https://github.com/shakacode/shakapacker/blob/main/docs/installation.md

Run this command after installation to check the generated configuration and build process.

```bash
bundle exec rake shakapacker:verify_install
```

--------------------------------

### Install CoffeeScript Loader Package

Source: https://github.com/shakacode/shakapacker/blob/main/docs/node_package_api.md

Install the `coffeescript` and `coffee-loader` packages for CoffeeScript support.

```bash
npm install coffeescript coffee-loader
```

--------------------------------

### Install SWC Core and SWC Loader

Source: https://github.com/shakacode/shakapacker/blob/main/docs/using_swc_loader.md

Install the necessary packages for SWC transpilation. This is required when switching from older Shakapacker versions.

```bash
npm install @swc/core swc-loader
```

--------------------------------

### Install SWC Dependencies

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Install the necessary SWC core and loader packages as development dependencies using Yarn, npm, or pnpm.

```bash
# Using Yarn
yarn add --dev @swc/core swc-loader

# Using npm
npm install --save-dev @swc/core swc-loader

# Using pnpm
pnpm add --save-dev @swc/core swc-loader
```

--------------------------------

### Initialize Shakapacker Build Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/configuration.md

Generates the initial config/shakapacker-builds.yml file with example build configurations.

```bash
bin/shakapacker --init
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Install project dependencies using pnpm. This action generates a pnpm-lock.yaml file.

```bash
pnpm install
```

--------------------------------

### Run Shakapacker Development Server

Source: https://github.com/shakacode/shakapacker/blob/main/docs/configuration.md

Starts the webpack development server for live updates during development.

```bash
./bin/shakapacker-dev-server
```

--------------------------------

### Install shakapacker-rspack with bun

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md

Use this command to install the shakapacker-rspack package with bun. This method bundles the full Rspack stack and is recommended for Shakapacker 10.1+.

```bash
bun add shakapacker-rspack -D
```

--------------------------------

### Webpack Configuration Example for Context

Source: https://github.com/shakacode/shakapacker/blob/main/docs/troubleshooting.md

An example of overriding the Webpack 'context' setting. Overriding this can lead to incorrect static file paths if not handled carefully.

```javascript
{
  context: path.resolve(__dirname, '../../app/javascript')
}
```

--------------------------------

### Run Shakapacker Installer with Skip Option

Source: https://github.com/shakacode/shakapacker/blob/main/docs/installation.md

Use this command to keep existing files and only create missing generated files during installation. Accepts truthy values like 'true', '1', or 'yes'.

```bash
# Keep existing files and create only missing generated files
SKIP=true bundle exec rake shakapacker:install
```

--------------------------------

### Start Rails with Puma's --early-hints Flag

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints_manual_api.md

Start your Rails application with Puma using the --early-hints flag to enable HTTP/1.1 early hints. This is required for both development and production testing.

```bash
# Option 1: Test in development (if enabled above)
bundle exec puma --early-hints
```

```bash
# Option 2: Test in production mode locally (more realistic)
RAILS_ENV=production bundle exec rake assets:precompile  # Compile assets first
RAILS_ENV=production bundle exec puma --early-hints -e production
```

--------------------------------

### Generate default Rspack configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md

Create a `config/rspack/rspack.config.js` file and use `generateRspackConfig` from `shakapacker/rspack` to get the default Rspack configuration. This is the starting point for Rspack setup.

```javascript
const { generateRspackConfig } = require("shakapacker/rspack")

module.exports = generateRspackConfig()
```

--------------------------------

### Scenario 3: Blog with Varied Content Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Implement different early hint strategies for blog index and show pages. The index page uses standard preloading for CSS/JS, while the show page uses prefetching to prioritize images.

```ruby
class ArticlesController < ApplicationController
  # Index: no large images
  configure_pack_early_hints only: [:index], css: 'preload', js: 'preload'

  # Show: featured images
  configure_pack_early_hints only: [:show], css: 'prefetch', js: 'prefetch'
end
```

--------------------------------

### Configure Code Splitting with Rspack

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack_migration_guide.md

Adapt Webpack's `splitChunks` configuration for Rspack. This example demonstrates a common setup for caching vendor modules.

```javascript
optimization: {
  splitChunks: {
    chunks: 'all',
    cacheGroups: {
      vendor: {
        test: /[\/]node_modules[\/]/,
        priority: -10,
        reuseExistingChunk: true
      }
    }
  }
}
```

--------------------------------

### Initialize Build Configuration File

Source: https://github.com/shakacode/shakapacker/blob/main/docs/troubleshooting.md

Create a .bundler-config.yml file with example build configurations using the --init flag. This command helps in setting up your project's build definitions.

```bash
bin/shakapacker-config --init
```

--------------------------------

### Run Shakapacker Dev Server

Source: https://github.com/shakacode/shakapacker/blob/main/docs/installation.md

Start the development server for Shakapacker to enable hot-reloading and other development features.

```bash
bin/shakapacker-dev-server
```

--------------------------------

### Example Usage of Shakapacker Types

Source: https://github.com/shakacode/shakapacker/blob/main/package/types/README.md

Demonstrates how to use the imported `Config` and `WebpackConfigWithDevServer` types to define configuration objects.

```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
}
```

--------------------------------

### React Entry Point (application.jsx)

Source: https://github.com/shakacode/shakapacker/blob/main/docs/react.md

Create a React entry point file that imports React components and renders them to a DOM element. This setup assumes SWC or Rspack is used for transpilation.

```jsx
import { createRoot } from "react-dom/client"
import App from "../App"

const container = document.getElementById("root")

if (container) {
  const root = createRoot(container)
  root.render(<App />)
}
```

--------------------------------

### Install Shakapacker with Webpack

Source: https://github.com/shakacode/shakapacker/blob/main/docs/installation.md

Install Shakapacker using Webpack as the assets bundler. Ensure your package manager is installed beforehand.

```bash
SHAKAPACKER_ASSETS_BUNDLER=webpack bundle exec rake shakapacker:install
```

```bash
bundle exec rake 'shakapacker:install[webpack]'
```

--------------------------------

### Full Example: Mixed Patterns in Controller and View

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints_manual_api.md

Demonstrates using early hints in a slow controller (Pattern 2) and dynamically loading packs in a view override (Pattern 3). Ensures hints are sent early for performance.

```ruby
# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    # Fast controller, automatic hints work fine (Pattern 1)
  end

  def show
    # Slow controller, send hints early for parallelism (Pattern 2)
    send_pack_early_hints({
      "application" => { js: "preload", css: "preload" }
    })

    # Expensive work happens in parallel with browser downloads
    @post = Post.includes(:comments, :author).find(params[:id])
  end
end
```

```erb
<%# app/views/posts/show.html.erb %>
<% if current_user&.admin? %>
  <%# Pattern 3: Dynamic pack loading based on user role %>
  <% append_javascript_pack_tag 'admin_tools' %>
<% end %>
```

```erb
<%# app/views/layouts/application.html.erb %>
<!DOCTYPE html>
<html>
  <head>
    <%= stylesheet_pack_tag 'application' %>
  </head>
  <body>
    <%= yield %>

    <%# Sends hints for application + admin_tools (if appended) %>
    <%# Won't duplicate hints already sent in controller %>
    <%= javascript_pack_tag 'application' %>
  </body>
</html>
```

--------------------------------

### Install TypeScript Dependencies

Source: https://github.com/shakacode/shakapacker/blob/main/docs/typescript-migration.md

Install the necessary TypeScript and type definition packages for Shakapacker and Webpack. Use either yarn or npm for installation.

```bash
yarn add --dev typescript @types/node @types/webpack
# or
npm install --save-dev typescript @types/node @types/webpack
```

--------------------------------

### Setup Shakapacker Dummy App with Yalc

Source: https://github.com/shakacode/shakapacker/blob/main/spec/dummy/README.md

Steps to publish the local shakapacker package using yalc and link it to the dummy app for development.

```bash
yalc publish

cd spec/dummy
bundle install
yalc link shakapacker
npm install
yalc link shakapacker
```

--------------------------------

### Local Ruby Gem Setup

Source: https://github.com/shakacode/shakapacker/blob/main/CONTRIBUTING.md

Configure your `Gemfile` to point to a local Shakapacker project for development.

```ruby
gem 'shakapacker', path: "relative_or_absolute_path_to_local_shakapacker"
```

--------------------------------

### Install shakapacker-rspack with npm

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md

Use this command to install the shakapacker-rspack package, which bundles the full Rspack stack. This is the recommended installation method for Shakapacker 10.1+.

```bash
npm install shakapacker-rspack -D
```

--------------------------------

### Configure pnpm Workspace

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Optional: Define package locations for monorepo setups using a pnpm-workspace.yaml file.

```yaml
packages:
  - "packages/*"
```

--------------------------------

### Manual Precompile Steps (Before)

Source: https://github.com/shakacode/shakapacker/blob/main/docs/precompile_hook.md

Shows the manual commands required for development and production before using the precompile hook.

```bash
# Development
bundle exec rake react_on_rails:generate_packs
bundle exec rake react_on_rails:locale
bin/shakacpacker-dev-server

# Production
bundle exec rake react_on_rails:generate_packs
bundle exec rake react_on_rails:locale
RAILS_ENV=production rake assets:precompile
```

--------------------------------

### Add postinstall Script for patch-package

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack_migration_guide.md

Add the `patch-package` command to the `postinstall` script in your `package.json` to automatically apply patches after installation.

```json
{
  "scripts": {
    "postinstall": "patch-package"
  }
}
```

--------------------------------

### Scenario 2: Interactive Dashboard Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Configure early hints for an interactive dashboard by setting `all: 'preload'`. This ensures that JavaScript, critical for the app's functionality, is loaded as quickly as possible.

```ruby
class DashboardController < ApplicationController
  # JS is critical for all actions
  configure_pack_early_hints all: 'preload'
end
```

--------------------------------

### Install Sass Loader Package

Source: https://github.com/shakacode/shakapacker/blob/main/docs/node_package_api.md

Install the `sass-loader` package for Sass support.

```bash
npm install sass-loader
```

```bash
npm install sass
```

--------------------------------

### Run Test Suite

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Execute your test suite to ensure all functionality works as expected after migrating to SWC.

```bash
# Ensure everything works as expected
bundle exec rspec
```

--------------------------------

### Valid Precompile Hook Paths

Source: https://github.com/shakacode/shakapacker/blob/main/docs/precompile_hook.md

Examples of valid configurations for the precompile_hook, ensuring the script is within the project root.

```yaml
# ✅ Valid - within project
precompile_hook: 'bin/shakapacker-precompile-hook'
precompile_hook: 'script/prepare-assets'
precompile_hook: 'bin/hook --arg1 --arg2'
```

--------------------------------

### Compare Client vs Server Bundles

Source: https://github.com/shakacode/shakapacker/blob/main/docs/config-diff.md

Compare production client and server bundles to identify differences between them. Ensure configurations are exported before diffing.

```bash
bin/shakapacker-config --doctor

bin/diff-bundler-config \
  --left=shakapacker-config-exports/webpack-production-client.yaml \
  --right=shakapacker-config-exports/webpack-production-server.yaml
```

--------------------------------

### List Available Builds

Source: https://github.com/shakacode/shakapacker/blob/main/docs/troubleshooting.md

Display all the build configurations that are currently defined and available in your project's configuration files.

```bash
bin/shakapacker-config --list-builds
```

--------------------------------

### Using the `test-bundler` Script

Source: https://github.com/shakacode/shakapacker/blob/main/spec/dummy/README.md

Demonstrates how to use the `test-bundler` script to switch between Webpack and RSpack, and to run commands with a specific bundler.

```bash
# Switch to webpack
bin/test-bundler webpack

# Switch to rspack
bin/test-bundler rspack

# Switch and run a command
bin/test-bundler webpack bin/shakapacker
bin/test-bundler rspack yarn build
```

--------------------------------

### Test Build with npm

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Verify the build process after migrating to npm by running the build script.

```bash
npm run build
```

--------------------------------

### Dynamic Early Hints for Mixed Content Types

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Configure early hints dynamically based on the post's content type. Use 'none' for LCP assets like videos, 'preload' for critical JS, and 'prefetch' for images or non-critical assets.

```ruby
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    case @post.content_type
    when 'video'
      # Video is LCP
      configure_pack_early_hints all: 'none'
    when 'interactive'
      # JS needed immediately
      configure_pack_early_hints css: 'prefetch', js: 'preload'
    when 'image_gallery'
      # Images are LCP
      configure_pack_early_hints all: 'prefetch'
    else
      # Standard text post
      configure_pack_early_hints css: 'preload', js: 'prefetch'
    end
  end
end
```

--------------------------------

### Install Less Loader Package

Source: https://github.com/shakacode/shakapacker/blob/main/docs/node_package_api.md

Install the `less` and `less-loader` packages for Less support.

```bash
npm install less less-loader
```

--------------------------------

### Example RBS Signature (Good Practice)

Source: https://github.com/shakacode/shakapacker/blob/main/CONTRIBUTING.md

Demonstrates good practices for writing RBS signatures, using specific types and documenting optional parameters.

```rbs
# Good: Specific types with documentation
class Shakapacker::Configuration
  def initialize: (
    root_path: Pathname,
    config_path: Pathname,
    env: ActiveSupport::StringInquirer,
    ?bundler_override: String?
  ) -> void

  def source_path: () -> Pathname
  def webpack?: () -> bool
  def assets_bundler: () -> String
end

# Module with singleton methods (using extend self)
module Shakapacker : _Singleton
  def self.config: () -> Configuration
  def self.compile: () -> bool
end
```

--------------------------------

### Changelog Example Format

Source: https://github.com/shakacode/shakapacker/blob/main/CLAUDE.md

Follow the specified format for changelog entries, including PR links and author attribution. Use '#' for PR numbers in links.

```markdown
[PR #123](https://github.com/shakacode/shakapacker/pull/123) by [username](https://github.com/username)
```

--------------------------------

### Install CSS Loader Packages

Source: https://github.com/shakacode/shakapacker/blob/main/docs/node_package_api.md

Install necessary npm packages to enable CSS support in your application.

```bash
npm install css-loader style-loader mini-css-extract-plugin css-minimizer-webpack-plugin
```

--------------------------------

### Custom Environment Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/configuration.md

Shows how to configure custom environments like 'staging' either explicitly or by allowing them to fall back to the 'production' configuration.

```yaml
# Option 1: Explicit staging config
staging:
  <<: *default
  compile: false
  # staging-specific options

# Option 2: Let staging fall back to production
# (no staging section needed)

```

--------------------------------

### Compare Development vs Production Client Config

Source: https://github.com/shakacode/shakapacker/blob/main/docs/config-diff.md

Compare the development and production client configurations using `diff-bundler-config`. The `--format=summary` option provides a concise overview of differences.

```bash
bin/diff-bundler-config \
  --left=shakapacker-config-exports/webpack-development-client.yaml \
  --right=shakapacker-config-exports/webpack-production-client.yaml \
  --format=summary
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

After removing yarn.lock, install project dependencies using npm. This will generate a package-lock.json file.

```bash
npm install
```

--------------------------------

### Global Configuration for Early Hints

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Enable and configure default early hints behavior for CSS and JS globally. Defaults to 'preload' if not specified when enabled.

```yaml
production:
  early_hints:
    enabled: true # Master switch
    css: "preload" # 'preload' | 'prefetch' | 'none'
    js: "preload" # 'preload' | 'prefetch' | 'none'
```

--------------------------------

### Install React Refresh Plugin for Rspack

Source: https://github.com/shakacode/shakapacker/blob/main/docs/transpiler-migration.md

For React projects using Rspack, install the react-refresh-plugin as a development dependency.

```bash
# For rspack
yarn add --dev @rspack/plugin-react-refresh
```

--------------------------------

### Run Release Task (Recommended)

Source: https://github.com/shakacode/shakapacker/blob/main/docs/releasing.md

Executes the release task, which reads the version from CHANGELOG.md and handles the publishing process. Ensure CHANGELOG.md is updated first.

```bash
bundle exec rake release
```

--------------------------------

### Install React Refresh Plugin for Webpack

Source: https://github.com/shakacode/shakapacker/blob/main/docs/transpiler-migration.md

For React projects using Webpack, install the react-refresh-webpack-plugin as a development dependency.

```bash
# For webpack
yarn add --dev @pmmmwh/react-refresh-webpack-plugin
```

--------------------------------

### Configure Early Hints in Before Action

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Set up early hint configurations that apply to multiple actions by defining them in a `before_action` filter. This promotes DRY principles for common hint strategies.

```ruby
class PostsController < ApplicationController
  before_action :optimize_for_images, only: [:gallery, :portfolio]

  private

  def optimize_for_images
    configure_pack_early_hints css: 'prefetch', js: 'prefetch'
  end
end
```

--------------------------------

### Install Shakapacker for Existing Rails App

Source: https://github.com/shakacode/shakapacker/blob/main/README.md

Add the shakapacker gem to your existing Rails application and run the installation task.

```bash
bundle add shakapacker --strict
bundle exec rake shakapacker:install
```

--------------------------------

### Useful Options for Diffing

Source: https://github.com/shakacode/shakapacker/blob/main/docs/config-diff.md

Demonstrates useful options for `diff-bundler-config`, including including unchanged values, limiting recursion depth, ignoring specific keys or paths, and disabling path normalization.

```bash
# Include unchanged values
--include-unchanged

# Limit recursion depth
--max-depth=5

# Ignore keys globally
--ignore-keys=timestamp,version

# Ignore paths (supports wildcards)
--ignore-paths="plugins.*,output.path"

# Disable automatic path normalization
--no-normalize-paths
```

--------------------------------

### Installing Dependencies for RSpack

Source: https://github.com/shakacode/shakapacker/blob/main/spec/dummy/README.md

Commands to install all project dependencies or specifically add RSpack-related packages if facing missing dependency errors.

```bash
# Install all dependencies
yarn install

# Or specifically for rspack
yarn add @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin
```

--------------------------------

### Check Manifest for Entrypoints

Source: https://github.com/shakacode/shakapacker/blob/main/docs/feature_testing.md

Verify that the `manifest.json` file exists and contains the expected entrypoints for your compiled assets. This is a fundamental check for asset compilation.

```bash
cat public/packs/manifest.json | jq .
```

--------------------------------

### Perform a Beta Release

Source: https://github.com/shakacode/shakapacker/blob/main/docs/releasing.md

Initiate a beta release by specifying the beta version. The task automatically converts the Ruby gem format to npm semver format.

```bash
bundle exec rake "release[10.2.0.beta.1]"  # Gem: 10.2.0.beta.1, npm: 10.2.0-beta.1
```

--------------------------------

### Install Shakapacker with Webpack and Babel

Source: https://github.com/shakacode/shakapacker/blob/main/docs/installation.md

Install Shakapacker with Webpack and explicitly set Babel as the JavaScript transpiler. Rspack ignores this setting.

```bash
SHAKAPACKER_ASSETS_BUNDLER=webpack JAVASCRIPT_TRANSPILER=babel bundle exec rake shakapacker:install
```

--------------------------------

### Heroku Deployment Steps

Source: https://github.com/shakacode/shakapacker/blob/main/docs/deployment.md

Steps to set up a Shakapacker application on Heroku, including creating an app, adding buildpacks, and pushing code. Ensure the NodeJS buildpack runs before Ruby for successful precompilation.

```bash
heroku create my-shakapacker-heroku-app
heroku addons:create heroku-postgresql:hobby-dev
heroku buildpacks:add heroku/nodejs
heroku buildpacks:add heroku/ruby
git push heroku HEAD:main
```

--------------------------------

### Example Shakapacker Build Configuration File

Source: https://github.com/shakacode/shakapacker/blob/main/docs/configuration.md

Defines reusable build configurations with options for environment, outputs, and custom configurations.

```yaml
builds:
  dev-hmr:
    description: Client bundle with HMR (React Fast Refresh)
    bundler: rspack # Optional: override assets_bundler from config/shakapacker.yml
    environment:
      NODE_ENV: development
      RAILS_ENV: development
      WEBPACK_SERVE: "true" # Automatically uses bin/shakapacker-dev-server
    outputs:
      - client
    config: config/${BUNDLER}/custom.config.js # Optional: custom config file with variable substitution

  prod:
    description: Production client and server bundles
    environment:
      NODE_ENV: production
      RAILS_ENV: production
    outputs:
      - client # Multiple outputs - builds both client and server bundles
      - server
```

--------------------------------

### Test Build with Yarn

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Confirm the build process is functioning correctly after migrating to Yarn.

```bash
yarn build
```

--------------------------------

### Test Build with pnpm

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Verify the build process after migrating to pnpm by executing the build script.

```bash
pnpm run build
```

--------------------------------

### Install shakapacker-rspack with pnpm

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md

Use this command to install the shakapacker-rspack package with pnpm. This method bundles the full Rspack stack and is recommended for Shakapacker 10.1+.

```bash
pnpm add shakapacker-rspack -D
```

--------------------------------

### Install shakapacker-rspack with yarn

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md

Use this command to install the shakapacker-rspack package with yarn. This method bundles the full Rspack stack and is recommended for Shakapacker 10.1+.

```bash
yarn add shakapacker-rspack -D
```

--------------------------------

### Configure Early Hints Per Action (Class Method)

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Configure early hints for specific controller actions using `configure_pack_early_hints`. You can specify preloading or prefetching strategies for CSS and JavaScript, or use the `all` shortcut.

```ruby
class PostsController < ApplicationController
  # Configure specific actions
  configure_pack_early_hints only: [:show], css: 'prefetch', js: 'preload'
  configure_pack_early_hints only: [:gallery], css: 'none', js: 'none'

  # Use 'all' shortcut
  configure_pack_early_hints only: [:about], all: 'prefetch'

  # Mix general and specific (specific wins)
  configure_pack_early_hints only: [:dashboard], all: 'preload', css: 'prefetch'
  # Result: css='prefetch', js='preload'
end
```

--------------------------------

### Basic Build Verification Commands

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack_migration_guide.md

Run these commands to clean previous build artifacts and test development and production builds. Verify that assets are generated correctly in the public/packs directory.

```bash
# Clean previous build artifacts
rm -rf public/packs public/packs-test

# Test development build
bin/shakapacker

# Test production build
RAILS_ENV=production bin/shakapacker

# Verify assets were generated
ls -la public/packs/
```

--------------------------------

### Install patch-package for ReScript Dependencies

Source: https://github.com/shakacode/shakapacker/blob/main/docs/rspack_migration_guide.md

Install `patch-package` as a development dependency to fix issues with ReScript packages that lack compiled files or have incorrect `bsconfig.json` configurations.

```bash
npm install --save-dev patch-package
```

--------------------------------

### Scenario 1: Image-Heavy Landing Page Configuration

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Optimize an image-heavy landing page by disabling CSS hints and using a low-priority JS hint. This prioritizes bandwidth for the hero image, improving LCP.

```ruby
class HomeController < ApplicationController
  def index
    # Save bandwidth for hero image
    configure_pack_early_hints css: 'none', js: 'prefetch'
  end
end
```

--------------------------------

### Asset Path and URL Helpers

Source: https://github.com/shakacode/shakapacker/blob/main/docs/api-reference.md

Use `asset_pack_path` to get the path to a pack asset and `asset_pack_url` to get its full URL. These are useful for referencing assets directly.

```ruby
<%= asset_pack_path 'logo.svg' %>
```

```ruby
<%= asset_pack_url 'logo.svg' %>
```

--------------------------------

### Install and Configure React Refresh Plugin for Rspack

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

If using React, install the `@rspack/plugin-react-refresh` package and add `ReactRefreshRspackPlugin` and `HotModuleReplacementPlugin` to your Rspack configuration for fast refresh during development.

```javascript
const { ReactRefreshRspackPlugin } = require("@rspack/plugin-react-refresh")
const { rspack } = require("@rspack/core")

module.exports = {
  plugins: [
    new ReactRefreshRspackPlugin(),
    new rspack.HotModuleReplacementPlugin()
  ]
}
```

--------------------------------

### Early Hints for E-commerce Product and Checkout Pages

Source: https://github.com/shakacode/shakapacker/blob/main/docs/early_hints.md

Configure different early hint strategies for product pages (prioritizing images) and checkout pages (prioritizing JavaScript for validation).

```ruby
class ProductsController < ApplicationController
  # Product page: images are critical
  configure_pack_early_hints only: [:show], css: 'prefetch', js: 'prefetch'

  # Checkout: form validation needs JS
  configure_pack_early_hints only: [:checkout], css: 'preload', js: 'preload'
end
```

--------------------------------

### Manual Rspack Dependency Installation

Source: https://github.com/shakacode/shakapacker/blob/main/docs/common-upgrades.md

Manually install Rspack dependencies using your preferred package manager (Yarn, npm, or pnpm). This is an alternative to the automated rake task.

```bash
yarn add --dev @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin
```

```bash
npm install --save-dev @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin
```

```bash
pnpm add --save-dev @rspack/core @rspack/cli @rspack/dev-server rspack-manifest-plugin
```

--------------------------------

### Install Shakapacker with Webpack

Source: https://github.com/shakacode/shakapacker/blob/main/docs/blog/2026-05-10-shakapacker-10-1-supplemental-packages.md

For new projects on npm 7+, install `shakapacker-webpack` to automatically include required Webpack core packages and `shakapacker`. This simplifies dependency management.

```sh
npm install --save-dev shakapacker-webpack
```

--------------------------------

### Configure Early Hints for Asset Loading

Source: https://github.com/shakacode/shakapacker/blob/main/docs/configuration.md

Enable and configure HTTP 103 Early Hints for faster asset loading. Specify hint types for CSS and JavaScript.

```yaml
early_hints:
  enabled: true # Master switch (default: false)
  css: "preload" # 'preload' | 'prefetch' | 'none' (default: 'preload')
  js: "preload" # 'preload' | 'prefetch' | 'none' (default: 'preload')
```