{"id":25718,"library":"hanami-assets","title":"Hanami Assets (esbuild plugin)","description":"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.","status":"active","version":"2.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/hanami/assets-js","tags":["javascript","hanami","assets","web","build","esbuild","plugin","typescript"],"install":[{"cmd":"npm install hanami-assets","lang":"bash","label":"npm"},{"cmd":"yarn add hanami-assets","lang":"bash","label":"yarn"},{"cmd":"pnpm add hanami-assets","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the plugin wraps esbuild for asset bundling.","package":"esbuild","optional":false},{"reason":"Required for file pattern matching in asset scanning.","package":"glob","optional":false}],"imports":[{"note":"ESM-only since v2; CommonJS require will error.","wrong":"const hanamiAssets = require('hanami-assets')","symbol":"default","correct":"import hanamiAssets from 'hanami-assets'"},{"note":"TypeScript users should use type import for Plugin type.","wrong":null,"symbol":"Plugin","correct":"import type { Plugin } from 'hanami-assets'"},{"note":"AssetEntry is a type representing manifest entries.","wrong":null,"symbol":"AssetEntry","correct":"import type { AssetEntry } from 'hanami-assets'"},{"note":"Options interface for configurePlugin.","wrong":null,"symbol":"PluginOptions","correct":"import type { PluginOptions } from 'hanami-assets'"}],"quickstart":{"code":"import hanamiAssets from 'hanami-assets';\nimport esbuild from 'esbuild';\n\nawait esbuild.build({\n  entryPoints: ['app/assets/javascripts/application.js'],\n  outdir: 'public/assets',\n  bundle: true,\n  plugins: [\n    hanamiAssets({\n      outDir: 'public/assets',\n      manifestPath: 'public/assets/manifest.json',\n      fingerprint: true\n    })\n  ]\n});\n\nconsole.log('Build complete with fingerprinting and manifest.');","lang":"javascript","description":"Bundles a JavaScript entry point with esbuild and Hanami assets plugin, generating fingerprinted assets."},"warnings":[{"fix":"Ensure hanamiAssets is the first plugin in the plugins array.","message":"Plugin must be placed before other esbuild plugins that modify asset paths.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade glob dependency to ^13.0.6.","message":"glob v11 and earlier produce deprecation warnings; bump glob to ^13.0.6.","severity":"deprecated","affected_versions":">=2.3.2"},{"fix":"Switch to ES module imports (import syntax) or use dynamic import().","message":"ESM-only from v2; CommonJS require throws error.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure manifestPath is writable and not used by another process.","message":"Manifest file must be writable; plugin overwrites existing manifest.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Replace require with import or use dynamic import().","cause":"Using CommonJS require() on an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported."},{"fix":"Use `import hanamiAssets from 'hanami-assets'` (ESM).","cause":"Incorrect import or missing default export.","error":"TypeError: hanamiAssets is not a function"},{"fix":"Create the output directory before running the build or set manifestPath correctly.","cause":"Output directory does not exist or is not writable.","error":"Error: ENOENT: no such file or directory, open '.../public/assets/manifest.json'"},{"fix":"Install esbuild: npm install esbuild --save-dev","cause":"Missing esbuild peer dependency.","error":"Error: esbuild is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}