Registry / devops / esbuild-html-link

esbuild-html-link

JSON →
library1.1.0jsnpmunverified

Post-processing tool for esbuild that replaces references to source files (like .ts, .tsx) in copied HTML entry files with the corresponding output files (e.g., .js, .css). It uses the esbuild metafile to map source entrypoints to their output bundles. Current version 1.1.0 requires esbuild >=0.24.1 because earlier versions do not mark HTML files as entrypoints in the metafile. It is a lightweight CLI tool (single binary) with no other runtime dependencies, designed to simplify esbuild HTML workflows.

devops
npm install esbuild-html-link
package ↗
INSTALL
IMPORT
SIG · ESBUILD-HTML-LINK
E
esbuild-html-link
devopsjavascriptv1.1.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default
✓ import esbuildHtmlLink from 'esbuild-html-link'
✗ const esbuildHtmlLink = require('esbuild-html-link')
The package is ESM-only; CommonJS require will fail.
linkHtmlEntries
✓ import { linkHtmlEntries } from 'esbuild-html-link'
✗ const { linkHtmlEntries } = require('esbuild-html-link')
Named export for programmatic use.
types
✓ import type { Options } from 'esbuild-html-link'
✗ import { Options } from 'esbuild-html-link'
Use type import for TypeScript types to avoid runtime errors.

Use esbuild-html-link programmatically with esbuild's JavaScript API. This example builds an HTML entry point, then rewrites script/src and link/href attributes in the copied HTML to point to output bundles.

import esbuild from 'esbuild'; import { linkHtmlEntries } from 'esbuild-html-link'; await esbuild.build({ entryPoints: ['src/index.html'], bundle: true, outdir: 'dist', metafile: true, loader: { '.html': 'copy' }, }).then(async (result) => { await linkHtmlEntries({ metafile: result.metafile!, // required htmlFiles: Object.keys(result.metafile!.inputs).filter(f => f.endsWith('.html')) }); });
Debug
Known issues
breakingRequires esbuild >=0.24.1 – older versions do not mark HTML files as entrypoints in metafile.
fix
Upgrade esbuild to >=0.24.1.
affects: <0.24.1
gotchaThe tool only processes HTML files that are entrypoints (not imported). Non-entry HTML files are ignored.
fix
Ensure your HTML files are listed as entryPoints in esbuild config.
affects: all
breakingESM-only package – does not export CommonJS via require().
fix
Use import syntax or dynamic import() in Node project with type: 'module'.
affects: >=1.0.0
deprecatedThe CLI command esbuild-html-link (without arguments) uses a default metafile path of 'meta.json'. Future versions may change default behavior.
fix
Always specify the metafile path explicitly with -m or --metafile.
affects: <=1.1.0
Errors
Common errors & fixes
Error: Cannot find module 'esbuild-html-link'
Using require('esbuild-html-link') in a CommonJS environment.
fix
Change to import statement or use dynamic import() in an ESM context.
TypeError: metafile is not defined
Forgetting to pass the metafile object when using the API.
fix
Ensure you pass the metafile from esbuild's build result: { metafile: result.metafile }.
Upgrade
Version history
1.1.0latest on npm
Audit
Dependencies
esbuildrequiredPeer dependency; reads metafile produced by esbuild to map source to output files. Must be >=0.24.1 for HTML entrypoint detection.
Agent activity
2 hits · last 30 days
node
2
Resources
packageesbuild-html-link ↗
esbuild-html-link — npm install esbuild-html-link · libregistry