Getting Started

Installation

Add the gem to your project:

$ bundle add web-packages

Your project also needs Node.js and one supported package manager: npm, pnpm, Yarn or Bun. Web Packages delegates dependency resolution and script execution to that package manager.

Add a JavaScript Dependency

Ruby applications commonly need browser libraries without needing a JavaScript bundler. Declare those libraries as regular production dependencies in package.json:

{
  "private": true,
  "packageManager": "pnpm@10",
  "dependencies": {
    "morphdom": "^2.7"
  }
}

Install the dependencies using the detected package manager:

$ bundle exec bake web:packages:install

The package manager remains responsible for its lock file and node_modules. Use immutable installation in CI:

$ bundle exec bake web:packages:install frozen=true

Select Browser Files

Packages often contain development sources, tests and metadata that should not be deployed. Add a web-packages section which selects the browser-facing files:

{
  "private": true,
  "packageManager": "pnpm@10",
  "dependencies": {
    "morphdom": "^2.7"
  },
  "web-packages": {
    "packages": {
      "morphdom": {
        "include": ["morphdom-esm.js"],
        "imports": {
          "morphdom": "morphdom-esm.js"
        }
      }
    }
  }
}

Direct production dependencies are selected by default. The package-specific object narrows the copied files and defines an import-map entry.

Generate Static Packages

Materialize the configured packages:

$ bundle exec bake web:packages:update

The default output is public/_components. Web Packages builds the complete output in a temporary directory and replaces the existing projection only after every package has been validated.

Print the generated browser import map:

$ bundle exec bake web:packages:import_map:show

For the example above, the result includes:

{
  "imports": {
    "morphdom": "/_components/morphdom/morphdom-esm.js"
  }
}

Your application can embed this JSON in a <script type="importmap"> element and serve public/_components with its other static assets.

Run JavaScript Tests

Web Packages runs scripts from the root package.json without imposing a test framework:

{
  "scripts": {
    "test": "node --test"
  }
}

$ bundle exec bake web:packages:test

Pass another script name when a project has multiple JavaScript test suites:

$ bundle exec bake web:packages:test script=test:browser

Verify Generated Files

Projects which commit or deploy the static projection can verify that it matches the current dependencies and configuration:

$ bundle exec bake web:packages:check

See the Static Packages guide for detailed selection, manifest and import-map configuration. See Internal Packages when JavaScript is developed alongside the Ruby code.