Skip to content
@staticbolt/core

Analyze Output Plugin

A plugin for staticbolt that analyzes each production build. It reports unused files, missing files, and files that go over a configured size limit. It can also keep the unused files out of the output directory.

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


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

The plugin only runs during production builds and has no effect in development.

Its write hook is enforce: "pre". It walks the pages before any file is written, wherever the plugin sits in the list. The checks in postBuild keep their place. List the plugin after anything that writes files on its own, like the sitemap or a search index, to have those files checked too.

What it checks

Unused files are the ones no HTML page references. The plugin walks every page and everything it links to, then reports the rest as warnings. With skipUnusedFiles it drops them from the build before they are written. No plugin spends time minifying, hashing or formatting them. Files copied from the public directory (publicDir in the config) are never reported or dropped.

Missing files are the ones that your HTML pages reference but that are not in the output directory once the build is done. The plugin reports them as errors.

Oversized files go over the configured size limit for their type. The plugin reports them as warnings, sorted by size from largest to smallest.

Any directory that ends up empty is removed.

Plugin Options

skipUnusedFiles

  • Type: boolean
  • Default: false

When true, unused files are never written to the output directory.

logUnusedFiles

  • Type: boolean
  • Default: false

Only the count of unused files is reported. Set to true to print the path of every one of them.

exclude

  • Type: string[]
  • Default: ["sitemap.xml", "sw.js", "workbox-*.js"]

Glob patterns for files to skip during analysis. A matched file is never reported as unused or missing, and never dropped.

analyzeOutputPlugin({
  exclude: ["robots.txt", "sitemap.xml", "_headers"],
});

maxFileSize

  • Type: Record<string, number> | false
  • Default: { ".js": 150 }

A map of file extensions to size limits in kilobytes. A file over its limit is reported as a warning. Set to false to turn size checking off.

analyzeOutputPlugin({
  maxFileSize: {
    ".js": 150,
    ".css": 50,
  },
});