Html-bundle NPM

html-bundle

A (primarily) zero-config bundler for HTML files. The idea is to use HTML as Single File Components, because HTML can already include <style> and <script> elements.

Features

🦾 TypeScript (reference it as .js or write inline TS)
📦 Automatic Package Installation
💨 HMR and automatic reconnect
⚡ ESBuild
🦔 Critical CSS
🚋 Watcher on PostCSS and Tailwind CSS and TS Config
🛡️ Almost no need to restart

Demo

Installation and Usage

$ npm install -D html-bundle

Add an entry to script in package.json (see flags below).

{
  "scripts": {
    "build": "html-bundle"
  }
}

Add a postcss.config.js file and run the build command. If you do not create this config file, a minimal in-memory config file will be created with cssnano as plugin.

$ npm run build

CLI

--hmr: boots up a static server and enables Hot Module Replacement. This generates a development build and works best when not triggered from the main index.html --secure: creates a secure HTTP2 over HTTPS instance. This requires the files localhost.pem and localhost-key.pem in the root folder. You can generate them with mkcert for instance. --isCritical: uses critical to extract and inline critical-path CSS to HTML. --handler: path to your custom handler. Here, you can handle all non-supported files. You can get the filename via process.argv[2].

Optional Config

The CLI flags can also be set by the config. Flags set by the CLI will override the config. Generate the config in the root and call it "bundle.config.js"

src: input path. Default to "src" build: output path. Defaults to "build" port: For the HMR Server. Defaults to 5000 deletePrev: Whether to delelte the build folder. Defaults to true esbuild: Your additional config html-minifier-terser: Your additional config critical: Your additional config

Example:

/** @type {import('html-bundle').Config} */
export default {
  secure: true,
  handler: "utils/staticFiles.js",
  esbuild: {
    external: ["images"],
  },
};

Concept

The bundler always globs all HTML, CSS and TS/JS files from the src (config) directory and processes them to the build (config) directory. PostCSS is being used for CSS files and inline styles, html-minifier-terser for HTML and esbuild to bundle, minify, etc. for inline and referenced TS/JS. Server-sent events and hydro-js are used for HMR. In order to trigger SPA Routers, the popstate event is being triggered after HMR Operations.

Example hydro-js

Get the idea from hydro-starter. Set "jsxFactory": "h" in tsconfig.json for JSX.

Input

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <meta name="Description" content="Example for html-bundle" />
    <script type="module">
      import { render, h, reactive } from "hydro-js";

      function Example({ name }) {
        return <main id="app">Hi {name}</main>;
      }

      const name = reactive("Tester");
      render(<Example name={name} />, "#app");
    </script>
    <style>
      body {
        background-color: whitesmoke;
      }
    </style>
  </head>
  <body>
    <main id="app"></main>
  </body>
</html>

Example Vue.js

Set "jsxFactory": "h" in tsconfig.json.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vue Example</title>
  </head>
  <script type="module">
    import { createApp, h } from "vue";

    const App = {
      data() {
        return {
          name: "Fabian",
        };
      },
      render() {
        return <p>{this.name}</p>;
      },
    };

    createApp(App).mount("#app");
  </script>
  <body>
    <div id="app"></div>
  </body>
</html>

Example React

Set "jsxFactory": "React.createElement" in tsconfig.json.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>React Example</title>
  </head>
  <script type="module">
    import React, { useState } from "react";
    import { createRoot } from "react-dom/client";

    function Example() {
      const [count, setCount] = useState(0);

      return (
        <div>
          <p>You clicked {count} times</p>
          <button onClick={() => setCount(count + 1)}>Click me</button>
        </div>
      );
    }

    createRoot(document.getElementById("app")).render(<Example />);
  </script>
  <body>
    <div id="app"></div>
  </body>
</html>

bundler SFC HTML TypeScript esbuild hydro-js

@fastify/static @web/parse5-utils await-spawn chokidar critters cssnano esbuild fastify glob html-minifier-terser hydro-js parse5 postcss postcss-load-config

@infinitebrahmanuniverse/nolb-html-b @everything-registry/sub-chunk-1867

2 months ago

3 months ago

3 months ago

3 months ago