html-bundle

library6.2.3jsnpmunverified

html-bundle is a primarily zero-config bundler designed for using HTML as Single File Components (SFCs), allowing inline `<style>` and `<script>` elements. It processes HTML, CSS, and TypeScript/JavaScript files from a source directory to a build directory, leveraging tools like ESBuild for bundling and minification, PostCSS for CSS processing, and html-minifier-terser for HTML. The package, currently at version 6.2.3, focuses on developer experience with features like automatic package installation, Hot Module Replacement (HMR) powered by Server-Sent Events and hydro-js, and critical CSS extraction via `beasties`. Its key differentiators include its HTML-first approach to componentization and its integrated tooling for a streamlined development workflow. The project appears actively maintained, though a clear release cadence isn't specified in the provided excerpt.

web-framework devops

npm install html-bundle

github ↗package ↗

INSTALL

IMPORT

SIG · HTML-BUNDLE

html-bundle

web-frameworkjavascriptv6.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

router

✓ import router from 'html-bundle';

✗ const router = require('html-bundle');

The programmatic API uses ESM default export. CommonJS `require()` is not supported for this entry point.

Config

✓ import type { Config } from 'html-bundle';

Type import for configuring html-bundle programmatically in TypeScript projects. Requires 'html-bundle' to be installed as a dev dependency.

cli

✓ html-bundle --flag

✗ node node_modules/html-bundle/dist/cli.js --flag

The primary interaction is via the `html-bundle` command-line interface, typically defined in `package.json` scripts.

This quickstart demonstrates how to set up `html-bundle` for both development (with HMR) and production builds, including a basic HTML Single File Component structure with inline styles and an optional client-side script using `hydro-js`.

{ "name": "my-html-project", "version": "1.0.0", "scripts": { "build": "html-bundle", "dev": "html-bundle --hmr --port 3000" }, "devDependencies": { "html-bundle": "^6.0.0" } } // src/index.html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>My HTML SFC</title> <style> body { font-family: sans-serif; background-color: #f0f0f0; } h1 { color: #333; } </style> </head> <body> <main id="app"> <h1>Hello, HTML Bundle!</h1> <script type="module"> import { reactive } from 'hydro-js'; // Optional: for reactivity const message = reactive('World'); document.querySelector('h1').textContent = `Hello, ${message}!`; console.log('App loaded and script executed.'); </script> </main> </body> </html> # Terminal commands to run the project npm install npm run build npm run dev

html-bundle --version

Debug

Known issues

gotchaWhen using the `--hmr` flag, `html-bundle` generates a development build. This mode is best suited for local development and might not function optimally if triggered from the main `index.html` due to specific HMR injection mechanisms.

fix

Use a dedicated entry point for HMR-enabled development if `index.html` is complex or serves as a multi-page entry. Ensure development server is configured correctly.

affects: >=6.0.0

gotchaEnabling secure HTTP2 over HTTPS with the `--secure` flag requires `localhost.pem` and `localhost-key.pem` files to be present in the project's root folder. Without these, the server will fail to start in secure mode.

fix

Generate the necessary TLS certificates using a tool like `mkcert` (e.g., `mkcert -install && mkcert localhost`) and place them in the root directory.

affects: >=6.0.0

gotchaConfiguration options provided via CLI flags will always override equivalent settings defined in a `bundle.config.js` file. Be aware of this precedence when debugging unexpected build behaviors.

fix

Prioritize CLI flags for temporary or environment-specific overrides. For persistent changes, modify `bundle.config.js`. When debugging, check both CLI args and config file.

affects: >=6.0.0

gotchaFor TypeScript projects using JSX directly in `<script type="module">` tags or imported components, you must configure `"jsxFactory": "h"` in your `tsconfig.json` to correctly transpile JSX syntax, especially when integrating with libraries like `hydro-js`.

fix

Add `"jsxFactory": "h"` under `compilerOptions` in your `tsconfig.json` file. Ensure `hydro-js` or a compatible JSX runtime is available.

affects: >=6.0.0

breakingVersion 6.x of `html-bundle` is primarily designed for ES Modules (ESM) in its programmatic API (e.g., `import router from 'html-bundle';`). Attempting to use CommonJS `require()` syntax for the main programmatic exports will result in errors.

fix

Ensure your project or script consuming `html-bundle` programmatically is set up for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` files) and uses `import` statements.

affects: >=6.0.0

Errors

Common errors & fixes

Error: Missing certificate file 'localhost.pem' or 'localhost-key.pem'

Attempting to run `html-bundle --secure` without the required TLS certificate and key files in the project root.

fix

Generate `localhost.pem` and `localhost-key.pem` using `mkcert` (`mkcert -install && mkcert localhost`) and place them in your project's root directory.

TypeError: 'createElement' is not a function or 'h' is not defined

JSX syntax is used in TypeScript files or inline scripts, but the TypeScript compiler or runtime is not configured to handle it correctly, often missing the `jsxFactory` setting.

fix

Add `"compilerOptions": { "jsxFactory": "h" }` to your `tsconfig.json` to inform TypeScript how to transpile JSX into function calls.

ERR_REQUIRE_ESM: require() of ES Module html-bundle/dist/index.js from ... not supported.

Attempting to `require('html-bundle')` in a CommonJS context when `html-bundle`'s main entry point is an ES Module.

fix

Refactor your consuming code to use ES Module `import` syntax. Ensure your environment supports ESM, or use dynamic `import('html-bundle')` if you must remain in a CommonJS file.

Error: ELOOP: too many symbolic links, stat 'src'

Misconfiguration of `src` or `build` paths in `bundle.config.js` or via CLI, potentially creating a recursive loop where the source directory includes the build directory, or vice-versa, leading to an infinite file globbing/processing loop.

fix

Verify that your `src` and `build` directories are distinct and do not contain each other. For example, if `src` is `./src`, then `build` should not be `./src/build`.

Upgrade

Version history

6.2.3latest on npm

Audit

Dependencies

hydro-jsoptionalUsed for Hot Module Replacement (HMR) and JSX support in client-side scripts.

postcssrequiredUsed internally for processing CSS files and inline styles, configurable via postcss.config.js.

esbuildrequiredPrimary bundler for TypeScript/JavaScript, including minification and other optimizations.

html-minifier-terserrequiredUsed for minifying HTML output files.

beastiesoptionalUsed for critical CSS extraction and inlining into HTML, enabled via --isCritical flag or config.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Krutsch/html-bundle ↗

packagehttps://www.npmjs.com/package/html-bundle ↗