Shakapacker

Shakapacker is the successor to rails/webpacker, providing a manifest-backed bridge between Rails and modern bundlers like webpack 5 or Rspack.

Key Features:

• Bundler Support: First-class support for Rspack (up to 17x faster than webpack), webpack 5, and managed bundler stacks via shakapacker-webpack or shakapacker-rspack (v10.1+).
• Transpilation: Supports JavaScript/TypeScript via SWC, Babel, or esbuild.
• Rails Integration: Native manifest integration and view helpers for bundled assets.
• Modern Web Dev: Support for Code splitting, HMR (Hot Module Replacement), CDN asset hosts, Subresource Integrity (SRI), and HTTP 103 Early Hints.
• Package Managers: Compatible with npm, Yarn, pnpm, and Bun.
• Optional Integrations: Extra packages are available for React, TypeScript, Sass, Less, Stylus, CSS, PostCSS, and CoffeeScript.

Choosing a JavaScript strategy for Rails depends on your frontend complexity. Use the following comparison to decide which tool fits your application needs:

When using the Address Review Prompt, the assistant categorizes fetched GitHub comments into three distinct groups to help you manage the review process:

• MUST-FIX: High-priority items including correctness bugs, regressions, security issues, missing tests that could hide bugs, and clear inconsistencies with adjacent code that would block a merge.
• DISCUSS: Items that require a decision, such as reasonable scope-expanding suggestions or architectural opinions.
• SKIPPED: Low-priority or non-actionable items like style preferences, documentation nits, speculative suggestions, or duplicate comments.

The assistant will present a summary of these counts and wait for your selection before proceeding to any code modifications.

In Shakapacker v9, NODE_ENV now intelligently defaults based on your RAILS_ENV. This ensures the development server correctly loads development configurations and uses the configured port instead of defaulting to 8080.

Default Mapping:

• RAILS_ENV=production $\rightarrow$ NODE_ENV defaults to "production"
• RAILS_ENV=development or RAILS_ENV=test $\rightarrow$ NODE_ENV defaults to "development"
• RAILS_ENV is unset or custom (e.g., staging) $\rightarrow$ NODE_ENV defaults to "production"

Cleanup: If you previously used workarounds to force development mode, you can now remove NODE_ENV=development from:

• .env, .env.development, or .env.local files
• docker-compose.yml or Dockerfile
• Custom scripts or bin/dev / Procfile.dev

Shakapacker v8 uses the packageManager property in your package.json to determine which JavaScript package manager to use. This is powered by the package_json gem.

If this property is missing, npm will be used by default. To ensure consistent behavior and avoid errors (especially when a lockfile other than package-lock.json is present), explicitly set the packageManager field. For example, if using Yarn, set it to yarn@<version>.

Note: The rake task check_yarn has been renamed to check_manager.

When determining which Early Hints to send, Shakapacker applies settings in the following order (later settings override earlier ones):

1. Global Configuration: Defined in shakapacker.yml.
2. Controller Class Configuration: Defined via configure_pack_early_hints at the class level.
3. Manual/Dynamic Configuration: Explicit calls to configure_pack_early_hints within an action or via manual API calls.

Within a single configuration call, the all: key is applied first, and then specific css: or js: keys will override those values.

To use HTTP 103 Early Hints in production, you must use a proxy architecture because Puma only supports HTTP/1.1 for Early Hints. The proxy handles HTTP/2 for external clients and translates requests to HTTP/1.1 for Puma.

Required Components:

• Puma 5+: Must be started with the --early-hints flag.
• HTTP/2-capable Proxy: The proxy must support translating 103 responses back to HTTP/2.
  • ✅ Supported: Thruster, nginx, Cloudflare.
  • ❌ Not Supported: Control Plane, AWS ALB.
• Rails 5.2+

Browser Behavior Note: Browsers only process the first HTTP/1.1 103 response. Shakapacker sends a single 103 response containing all combined hints (JS and CSS).

To prevent security vulnerabilities, Shakapacker enforces several restrictions on the precompile_hook path:

• Project Root Restriction: The hook must reference a script located within your project root. Paths like /usr/bin/malicious-script or ../../../etc/passwd are rejected.
• Symlink Resolution: Shakapacker resolves symlinks to their real paths before validation to ensure they do not point to files outside the project.
• Path Traversal Protection: Attempts to use .. to escape the project directory are blocked.
• Boundary Checking: The system uses proper path boundary checking (via File::SEPARATOR) to prevent partial path match exploits.

The Shakapacker module provides singleton-style access to the core functionality of the library, including configuration, compilation, manifest lookup, dev server status, and environment management. Most common tasks can be performed directly through this module.

# Access configuration
Shakapacker.config

# Compile assets
Shakapacker.compile

# Look up assets in manifest
Shakapacker.manifest.lookup("application.js")

# Check dev server status
Shakapacker.dev_server.running?

# Manage environment
Shakapacker.env