Skip to content
@staticbolt/core

HTML Bundle Script Plugin

A plugin for staticbolt that bundles <script> tags in HTML files using esbuild. Bundling is opt-in per tag via the bundle attribute.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { htmlBundleScriptPlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [htmlBundleScriptPlugin()],
});

Bundling a script

Add the bundle attribute to any <script> tag to have it bundled at build time. The attribute never reaches the output. During development the plugin strips it and bundles nothing.

<script src="./app.js" bundle></script>

Output behavior

What the plugin writes depends on whether the script is inline or external, and on whether the tag sets a bundle-out path.

The bundle-out path always resolves from the output directory, no matter where the HTML file sits. bundle-out="./accordion.js" writes the bundle to dist/accordion.js whether the tag lives in index.html or pages/components/accordion.html.

External script, no bundle-out

The bundle goes to {filename}.bundle.js next to the original file, and the src attribute points at it instead.

<!-- Input -->
<script src="./app.js" bundle></script>


<!-- Output -->
<script src="./app.bundle.js"></script>

External script, with bundle-out

The bundle goes to the given path (relative to the output directory), and the src attribute points at it instead.

<!-- Input -->
<script src="./app.js" bundle bundle-out="./bundled-app.js"></script>


<!-- Output -->
<script src="./bundled-app.js"></script>

Inline script, no bundle-out

The bundled content replaces the tag's content in place.

<!-- Input -->
<script bundle>
  import { greet } from "./greet.js";


  greet();
</script>


<!-- Output -->
<script>
  function greet() {
    console.log("Hello, world!");
  }


  greet();
</script>

Inline script, with bundle-out

The plugin clears the tag's content, writes the bundle to the given path (relative to the output directory), and sets the src attribute to point at it.

<!-- Input -->
<script bundle bundle-out="./app.js">
  import { greet } from "./greet.js";


  greet();
</script>


<!-- Output -->
<script src="./app.js"></script>

Output format

Bundles are emitted as ESM by default. Add the iife attribute to emit an IIFE instead. The bundle then runs as a classic script and keeps its top-level scope private.

<!-- Input -->
<script src="./app.js" bundle iife></script>


<!-- Output -->
<script src="./app.bundle.js"></script>

The attribute is a boolean flag. Its value is ignored, and it never reaches the output. It only changes the output format that esbuild produces. The tag's type attribute is left untouched, so drop type="module" from the tag as well if the browser should not treat the result as a module.

Externals

By default, modules inside node_modules are treated as external and left out of the bundle. Override that globally with the plugin options, or per tag with attributes.

Global configuration

htmlBundleScriptPlugin({
  externals: ["**/node_modules/**", "**/vendor/**"],
  externalsExclude: ["**/node_modules/my-inlined-lib/**"],
});

Per tag

The bundle-externals attribute takes a semicolon-separated list of glob patterns for modules to treat as external. bundle-externals-exclude exempts modules from being external even if they match the externals patterns. Either attribute takes precedence over the global options for the tag it sits on.

<!-- Treat everything in vendor as external except one specific package -->
<script src="./app.js" bundle bundle-externals="**/vendor/**" bundle-externals-exclude="**/vendor/my-lib/**"></script>

Plugin Options

externals

  • Type: string[]
  • Default: ["**/node_modules/**"]

Glob patterns for modules to treat as external and leave out of the bundle.

externalsExclude

  • Type: string[]
  • Default: []

Glob patterns that exempt modules from being treated as external, even if they match externals.

bundleAttribute

  • Type: string
  • Default: "bundle"

The attribute name that opts a script tag into bundling.

bundleOutAttribute

  • Type: string
  • Default: "bundle-out"

The attribute name that sets the output file path for the bundled script.

externalsAttribute

  • Type: string
  • Default: "bundle-externals"

The attribute name that sets the external glob patterns for one tag, as a semicolon-separated list.

externalsExcludeAttribute

  • Type: string
  • Default: "bundle-externals-exclude"

The attribute name that sets the externals-exclude glob patterns for one tag, as a semicolon-separated list.

iifeAttribute

  • Type: string
  • Default: "iife"

The attribute name that switches a tag's bundle output format from ESM to IIFE. It is a present-or-absent flag and its value is ignored.