Skip to content
@staticbolt/core

HTML Preload Plugin

A plugin for staticbolt that generates <link rel="preload"> tags for the dependencies of your scripts and stylesheets. This tells the browser to start fetching those files early, before normal parsing discovers them.

Installation

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

Usage

In your .staticbolt.ts configuration file:

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


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

Preloading dependencies

Add the preload attribute to any <script>, <style>, or <link rel="stylesheet"> tag. At build time the plugin walks the full dependency graph of that file and injects a <link rel="preload"> tag into the <head> for every dependency it finds, the file itself included.

<link rel="stylesheet" href="./main.css" preload />
<script src="./app.js" preload></script>

Preload tags are only generated in production builds. In development the plugin strips the preload, preload-include, and preload-exclude attributes and adds no preload tags.

Filtering by asset type

By default, preload tags are generated for every dependency type the plugin finds: script, style, fetch, font, audio, video, and image. To limit preloading to specific types, pass a space-separated list of types as the value of the preload attribute.

<!-- Only preload fonts and images from this stylesheet's dependencies -->
<link rel="stylesheet" href="./main.css" preload="font image" />

Filtering by file path

Use the preload-include and preload-exclude attributes to control which dependency files get a preload tag. Both take a semicolon-separated list of glob patterns, matched against paths relative to the project root.

<!-- Only preload files inside the fonts directory -->
<link rel="stylesheet" href="./main.css" preload preload-include="**/fonts/**" />


<!-- Preload everything except vendor files -->
<script src="./app.js" preload preload-exclude="**/vendor/**"></script>

You can put both attributes on the same tag, and each one can list several patterns.

<script src="./app.js" preload preload-include="**/*" preload-exclude="**/vendor/**;**/legacy/**"></script>

Plugin Options

preloadAttribute

  • Type: string
  • Default: "preload"

The attribute name that enables preloading on a tag.

htmlPreloadPlugin({
  preloadAttribute: "prefetch",
});

includeAttribute

  • Type: string
  • Default: "preload-include"

The attribute name that holds the glob patterns of files to include, as a semicolon-separated list.

htmlPreloadPlugin({
  includeAttribute: "only",
});

excludeAttribute

  • Type: string
  • Default: "preload-exclude"

The attribute name that holds the glob patterns of files to exclude, as a semicolon-separated list.

htmlPreloadPlugin({
  excludeAttribute: "ignore",
});