DOCSEARCHbyAlgolia
Submit Docs

Shakapacker Documentation

website·Indexed 32 days ago

https://shakapacker.com

Documentation for Shakapacker, a JavaScript bundling solution for Ruby on Rails. It provides guides on installation, deployment, and integration with React and TypeScript, as well as support for Webpack and Rspack. Includes detailed migration paths for v7, v9, and v10, and performance optimization techniques such as HTTP 103 Early Hints and SWC or esbuild loaders.

Tokens
61.6K
Snippets
365
Records
505
Agent score
58%

What's inside Shakapacker

  1. Overview of Shakapacker 10.1 supplemental packages

    v10.1-supplemental-packages
    Shakapacker 10.1 introduces shakapacker-webpack and shakapacker-rspack. These optional packages declare the managed-build stack as required peerDependencies. Adopting them allows users on npm 7+ to replace multiple explicit bundler dependencies with a single package. This setup prevents duplicate-bundler risks (ensuring a single instance of webpack or @rspack/core) and prepares the application for v11, where these supplemental packages will be required for managed builds. This change is opt-in; apps that do not adopt them will continue to work as they did in 10.0.

  2. Overview of esbuild in Shakapacker

    Shakapacker supports esbuild-loader to leverage esbuild's speed for transpilation and minification within Webpack. Note that this feature is experimental. Unlike Babel or SWC, esbuild-loader does not support React Hot Module Reload (HMR), ES5 as a compilation target, or automatic polyfills for missing browser features.

  3. Overview of Shakapacker and Rspack

    Shakapacker is the actively maintained successor to rails/webpacker. It provides a Rails-native, manifest-backed bridge to full bundlers (webpack 5 or Rspack). It includes built-in support for view helpers, Hot Module Replacement (HMR), React Fast Refresh, code splitting, Subresource Integrity (SRI), CDN hosts, and HTTP 103 Early Hints.

    Rspack is a Rust-based, mostly webpack-compatible bundler that can be used with Shakapacker to significantly increase build speeds. Reported performance gains include roughly 8x faster production builds, 10–15x faster dev startup, and ~17x faster HMR compared to webpack.

  4. Overview of HTTP 103 Early Hints in Shakapacker

    HTTP 103 Early Hints are emitted after Rails finishes rendering but before the final response is sent. This allows browsers to begin fetching critical resources (JS, CSS) before the full HTML response is received, potentially improving page load performance.

    Critical Performance Warning: Preloading JavaScript can negatively impact the Largest Contentful Paint (LCP) metric if it competes for bandwidth with large images or videos.

    CDN Limitation: Most CDNs (e.g., Cloudflare, AWS CloudFront, AWS ALB) strip HTTP 103 responses. End users may only receive the 200 response with Link headers, which arrive too late to provide the benefits of early hints unless specific CDN features (like Cloudflare's paid Early Hints) are configured.

  5. Perform semantic diffs of bundler configurations

    Shakapacker provides a semantic configuration diff workflow via pack-config-diff. Unlike standard line-by-line file diffs, this tool understands nested webpack/rspack configuration objects, normalizes machine-specific absolute paths, and handles config-specific types like functions, RegExp, and Dates. It is primarily used to verify that behavior is preserved during webpack-to-Rspack migrations or to debug differences between development and production environments.

  6. Understand the Shakapacker multi-package dependency structure

    Shakapacker has split its functionality into three distinct npm packages to separate core logic from specific bundler requirements. This prevents version conflicts and reduces the number of unnecessary peer dependencies installed in a project.

    1. shakapacker (Core): The base package required by all users. It handles configuration loading, manifest reading, the dev server proxy, and the CLI. It has zero bundler-specific peer dependencies.
    2. shakapacker-webpack: A managed Webpack build package. It declares webpack, webpack-cli, and webpack-assets-manifest as required peer dependencies to ensure a singleton bundler stack.
    3. shakapacker-rspack: A managed Rspack build package. It declares @rspack/core, @rspack/cli, @rspack/dev-server, and rspack-manifest-plugin as required peer dependencies.

  7. Compare Shakapacker transpilers and bundlers

    Shakapacker supports multiple transpilers and bundlers. Moving away from Babel and webpack generally provides the most significant build performance gains.

    Transpilers:

    • SWC: Much faster than Babel (up to 20x single-thread / 70x multi-core). Recommended default for most new apps. Supports JS, TS, JSX, and TSX.
    • esbuild: Very fast, minimal configuration. Best for modern syntax and simple transform needs.
    • Babel: Baseline performance. Most flexible; essential for apps requiring specific Babel plugins, macros, or legacy browser targets.

    Bundlers:

    • Rspack: Substantially faster than webpack (roughly 8–17x). Mostly webpack-compatible. Best for maximum performance jumps.
    • webpack: Baseline performance. Largest ecosystem of plugins and loaders.

  8. Understand the Shakapacker multi-package npm structure

    Shakapacker has transitioned to a monorepo structure to isolate bundler-specific dependencies. The functionality is split into three distinct npm packages that follow lockstep versioning (all share the same version number):

    1. shakapacker: The core package containing shared logic.
    2. shakapacker-webpack: Provides a managed Webpack build.
    3. shakapacker-rspack: Provides a managed Rspack build.

  9. Understand the Shakapacker core package functionality

    The shakapacker (core) package provides the foundational logic required for any Shakapacker build, regardless of the bundler used. It handles:

    • Config loading (parsing shakapacker.yml and managing defaults)
    • Manifest reading and asset lookup
    • Dev server proxy client
    • CLI entry points (shakapacker, shakapacker-dev-server)
    • View helper support (Ruby gem reads the manifest generated by any build)
    • Shared utilities such as webpack-merge and config merging.

    In v11.0.0, this package is stripped of bundler and transpiler peer dependencies, allowing it to work standalone for users with custom build setups.

  10. Get support for Shakapacker

    Shakapacker is open source and can be used for free. Users can access support through two primary channels: Community support for general documentation and issue tracking, and Direct support via ShakaCode for professional services.

    Community support includes:

    • Public GitHub documentation and issue tracker
    • GitHub Discussions for community help
    • Self-service migration documentation

    Direct support from ShakaCode is available for teams requiring:

    • Guided migration for complex applications
    • Production hardening and performance tuning
    • Direct implementation support
    • Priority maintenance sponsorship

  11. Check Dev Server status and configuration

    The Shakapacker::DevServer class provides information about the development server's current state and connection settings.
    dev_server = Shakapacker.dev_server

# Status
dev_server.running?      # => true
dev_server.protocol      # => "http"
dev_server.host_with_port # => "localhost:3035"

# Configuration
dev_server.host           # => "localhost"
dev_server.port           # => 3035
dev_server.server         # => "http"
dev_server.hmr?           # => true

  12. Use TypeScript with Shakapacker v9

    Shakapacker v9 introduces TypeScript definitions to provide better IDE support (autocomplete) and compile-time type safety for configuration. This is optional; existing JavaScript configurations continue to work without modification.