Hanami Assets (esbuild plugin)

2.3.2 verified Fri May 01 auth: no javascript

An esbuild plugin for Hanami asset management, version 2.3.2 (stable, released March 2025). It integrates esbuild into the Hanami Ruby web framework pipeline, providing JavaScript/CSS bundling, fingerprinting, and asset helpers. Unlike standalone esbuild, this plugin respects Hanami's asset directory conventions and integrates with Hanami's view helpers for asset tags. Release cadence is irregular, tied to Hanami framework updates. It is ESM-only and ships TypeScript definitions.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported. ↓

cause Using CommonJS require() on an ESM-only package.

fix

Replace require with import or use dynamic import().

error TypeError: hanamiAssets is not a function ↓

cause Incorrect import or missing default export.

fix

Use import hanamiAssets from 'hanami-assets' (ESM).

error Error: ENOENT: no such file or directory, open '.../public/assets/manifest.json' ↓

cause Output directory does not exist or is not writable.

fix

Create the output directory before running the build or set manifestPath correctly.

error Error: esbuild is not defined ↓

cause Missing esbuild peer dependency.

fix

Install esbuild: npm install esbuild --save-dev

Warnings

gotcha Plugin must be placed before other esbuild plugins that modify asset paths. ↓

fix Ensure hanamiAssets is the first plugin in the plugins array.

deprecated glob v11 and earlier produce deprecation warnings; bump glob to ^13.0.6. ↓

fix Upgrade glob dependency to ^13.0.6.

breaking ESM-only from v2; CommonJS require throws error. ↓

fix Switch to ES module imports (import syntax) or use dynamic import().

gotcha Manifest file must be writable; plugin overwrites existing manifest. ↓

fix Ensure manifestPath is writable and not used by another process.

Install

npm install hanami-assets

yarn add hanami-assets

pnpm add hanami-assets

Imports

default

wrong

const hanamiAssets = require('hanami-assets')

correct

import hanamiAssets from 'hanami-assets'

ESM-only since v2; CommonJS require will error.

Plugin
```
import type { Plugin } from 'hanami-assets'
```
TypeScript users should use type import for Plugin type.
AssetEntry
```
import type { AssetEntry } from 'hanami-assets'
```
AssetEntry is a type representing manifest entries.

PluginOptions

import type { PluginOptions } from 'hanami-assets'

Options interface for configurePlugin.

Quickstart

Bundles a JavaScript entry point with esbuild and Hanami assets plugin, generating fingerprinted assets.

import hanamiAssets from 'hanami-assets';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['app/assets/javascripts/application.js'],
  outdir: 'public/assets',
  bundle: true,
  plugins: [
    hanamiAssets({
      outDir: 'public/assets',
      manifestPath: 'public/assets/manifest.json',
      fingerprint: true
    })
  ]
});

console.log('Build complete with fingerprinting and manifest.');