HTML Bundle

Common errors

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

  cause 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

  cause 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.

  cause 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'

  cause 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`.

Warnings

• gotcha When 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.
• gotcha Enabling 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.
• gotcha Configuration 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.
• gotcha For 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.
• breaking Version 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.

Install

• npm install html-bundle npm
• yarn add html-bundle yarn
• pnpm add html-bundle pnpm

Imports

• router
  wrong:

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

  correct:

  import router from '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
  wrong:

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

  correct:

  html-bundle --flag

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

Quickstart

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