Write Files Plugin

A staticbolt plugin that writes every processed file to the output directory at the end of a production build. It can clean the output directory before writing, and it can minify or format individual files that match a glob pattern.

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

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

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

Cleaning the output directory

Set clean: true to delete the entire output directory before writing. No stale file from an earlier build is left behind.

writeFilesPlugin({
  clean: true,
});

Choosing what gets written

include and exclude pick which files land in the output directory. Files that a plugin excluded from emitting are skipped either way.

writeFilesPlugin({
  exclude: ["**/*.map"],
});

Every glob in this plugin (include, exclude, and the patterns under minify and format) is matched against the path the file is written to, relative to the output directory, not the path it was read from. A plugin that moves or renames a file moves it out of the patterns its source used to match. Write the patterns against the output you expect.

Minification and formatting

Use the minify and format options to minify or format the output files. Both take glob patterns to target specific files. Minification and formatting are mutually exclusive. If both match the same file, only one of them runs and the plugin logs a warning.

writeFilesPlugin({
  minify: {
    enabled: true,
    include: ["**/*.js", "**/*.css"],
    exclude: ["**/vendor/**"],
  },
  format: {
    enabled: true,
    include: ["**/*.html"],
  },
});

Minifying and formatting are the slow part of writing a file, and neither runs on the main thread. Each file is written as it comes out of the pipeline, and its handler goes to a pool of worker threads that work through them while the remaining files are still being written. The plugin waits for the pool before it hands back. Every other plugin sees the finished output.

Plugin Options

clean

• Type: boolean

When true, the plugin deletes the output directory before writing begins.

include

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

Glob patterns for the files to write.

exclude

• Type: string[]
• Default: []

Glob patterns for the files to leave unwritten.

concurrency

• Type: number
• Default: one per core, up to eight

How many worker threads may minify or format output files at once. Every worker carries its own copy of whatever tooling the handler loads. Raise this only on a machine with the cores and memory to back it.

minify.enabled

• Type: boolean
• Default: false

Enables minification of output files.

minify.include

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

Glob patterns for files to minify.

minify.exclude

• Type: string[]
• Default: []

Glob patterns for files to exclude from minification.

format.enabled

• Type: boolean
• Default: false

Enables formatting of output files.

format.include

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

Glob patterns for files to format.

format.exclude

• Type: string[]
• Default: []

Glob patterns for files to exclude from formatting.