Shakapacker

10.0.0 verified Sat Apr 25 auth: no javascript

Shakapacker is the official, actively maintained successor to rails/webpacker that integrates Webpack v5+ (or Rspack for 10x faster builds) with Rails for managing app-like JavaScript modules. Version 10.0.0 requires Node >=20 and supports Rspack v2, esbuild, and SWC loaders. Released by ShakaCode with regular cadence (v9.6.2 latest stable, v10.0.0 recent), it provides a robust Ruby gem and npm package for configuration, asset manifest generation, and development server integration. Key differentiators: native Rspack support, semantic config diffing (bin/diff-bundler-config), and compatibility with jsbundling-rails alternatives. Ships TypeScript types.

Common errors

error Module not found: Error: Can't resolve 'shakapacker' ↓

cause Typo or missing dependency; shakapacker npm package not installed.

fix

Run 'yarn add shakapacker@^10.0.0' or 'npm install shakapacker@^10.0.0'.

error Unknown option: '--watch' for shakapacker ↓

cause Deprecated --watch flag removed in v10; use 'bin/shakapacker-watch' instead.

fix

Replace 'bin/shakapacker --watch' with 'bin/shakapacker-watch --watch' in Procfile or CLI.

error WebpackOptionsValidationError: Invalid configuration object: configuration has an unknown property 'optimization.splitChunks.chunks' ↓

cause webpack v5 removed splitChunks.chunks; use optimization.splitChunks.cacheGroups.

fix

Update webpack config to use cacheGroups instead of chunks. Refer to webpack 5 migration guide.

error Env#current raises NameError: undefined method `env' for nil:NilClass ↓

cause Calling Shakapacker::Env#current outside of Rails context (e.g., in bin/dev).

fix

Upgrade to shakapacker v9.6.1+ which adds defined?(Rails) guard, or manually set RAILS_ENV.

Warnings

breaking Shakapacker v9 dropped support for Node < 20. Upgrade Node.js to 20+ before updating. ↓

fix Update Node to 20.x or later. Verify with node --version.

breaking Shakapacker v10 removed deprecated event system hooks (pre_event, post_event). Use new hooks API. ↓

fix Replace event-based hooks with direct method overrides in ShakapackerConfig subclass.

deprecated Using 'require('shakapacker')' with CommonJS is deprecated in v10. Use ESM imports. ↓

fix Switch to import { shakapacker } from 'shakapacker' in ESM context, or use dynamic import() if mixed.

gotcha Rspack support requires peer dependency '@rspack/core' (>=1.0.0 or >=2.0.0-0). Missing this will cause silent fallback to webpack. ↓

fix Add '@rspack/core' to dependencies. If using webpack, ignore this warning.

gotcha DevServer CORS headers are disabled by default since v9.6.0. Cross-origin asset loading breaks if Rails and dev server on different ports. ↓

fix Uncomment 'headers' section in config/shakapacker.yml to restore Access-Control-Allow-Origin: *.

Install

npm install shakapacker

yarn add shakapacker

pnpm add shakapacker

Imports

shakapacker

wrong

const shakapacker = require('shakapacker')

correct

import { shakapacker } from 'shakapacker'

Named export, not default. Available in ESM and CommonJS contexts.

ShakapackerDeployment
```
import { ShakapackerDeployment } from 'shakapacker/deployment'
```
Common for deployment scripts; must be imported from 'shakapacker/deployment' subpath.
ShakapackerConfig
wrong
```
import { ShakapackerConfig } from 'shakapacker'
```
correct
```
import { ShakapackerConfig } from 'shakapacker/config'
```
Config class is separate from main package export. Ensure correct subpath import.

Quickstart

Shows basic imports from shakapacker npm package: main export, deployment, and config subpaths.

// Install: yarn add --dev shakapacker@^10.0.0
// Then configure webpack.config.js or rspack.config.js
const { shakapacker } = require('shakapacker');

// Example: get public output path
const publicPath = shakapacker.publicOutputPath;
console.log('Public path:', publicPath);

// For deployment manifest
const { ShakapackerDeployment } = require('shakapacker/deployment');
const deployment = new ShakapackerDeployment({ manifestPath: './public/packs/manifest.json' });
deployment.deploy();

// For configuration reading
const { ShakapackerConfig } = require('shakapacker/config');
const config = new ShakapackerConfig();
console.log('Dev server enabled:', config.devServer?.enabled);