HTML Build Time Script Plugin

A plugin for staticbolt that runs scripts at build time and applies their DOM changes to the HTML output. The script tag is removed from the final page.

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 { htmlBuildTimeScript } from "@staticbolt/core/plugins";

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

Running a script at build time

Add the build-time attribute to a <script> tag, either inline or with a src attribute. The script runs once the page is fully constructed, and it has access to the page's DOM. Changes it makes to the DOM show up in the final HTML output, and the script tag itself is removed.

Inline:

<script build-time>
  const items = ["Apple", "Banana", "Cherry"];
  const list = document.createElement("ul");

  for (const item of items) {
    const li = document.createElement("li");
    li.textContent = item;
    list.appendChild(li);
  }

  document.querySelector("#fruit-list").replaceWith(list);
</script>

External file:

<script build-time src="./generate-content.js"></script>

Editor support

Mark an inline build-time script with type="application/x-typescript" and the Staticbolt language server serves it through the project's TypeScript: completions, hover, type errors and highlighting. It declares StaticBolt, document, window, __filepath and __id. document is typed as the parser's tree, or as the DOM's when the full DOM attribute is present. The core HTML plugin uses the same type for browser scripts. A build-time script gets the sandbox's types instead of the browser's.

<script build-time type="application/x-typescript">
  const heading = document.querySelector("h1");
  heading?.setAttribute("data-page", __id);
</script>

Plugin Options

buildAttribute

• Type: string
• Default: "build-time"

The attribute name that marks a script tag for build-time execution.

htmlBuildTimeScript({
  buildAttribute: "ssr",
});

fullDomAttribute

• Type: string
• Default: "full-dom"

The attribute name on the script tag that opts into a full DOM context using jsdom. When it is not present, the plugin uses the lighter @staticbolt/node-html-parser instead.

<script build-time full-dom>
  /* script that requires a full DOM environment */
</script>

Choosing the right parser:

• Use the default @staticbolt/node-html-parser when your script does simple DOM manipulation and doesn't depend on browser-specific APIs. It parses any HTML fragment and is much faster.
• Add the full-dom attribute when your script relies on the full browser DOM API (e.g. Canvas, getComputedStyle, layout-dependent queries). jsdom needs the page to be fully constructed, so put this plugin last in your plugin order.

htmlBuildTimeScript({
  fullDomAttribute: "jsdom",
});

contextAttribute

• Type: string
• Default: "context"

The attribute name on the script tag that holds a JSON object. Its entries become globals for the script while it runs. Use it to reuse the same external script across pages with different values.

<script build-time context='{ "heading": "Fruits", "items": ["Apple", "Banana"] }' src="./generate-list.js"></script>

document.querySelector("h1").textContent = heading;

for (const item of items) {
  /* ... */
}

The value must be valid JSON. If it fails to parse, the plugin logs an error and the script still runs without the extra globals. Entries are applied after the built-in globals (document, window, StaticBolt, __filepath, __id). Reusing one of those names overrides it.

htmlBuildTimeScript({
  contextAttribute: "props",
});