Skip to content
@staticbolt/core

Serve CLI Plugin

A staticbolt CLI plugin that registers a serve command for checking a production build before you ship it. It serves the files already on disk over HTTP. It never builds, so run staticbolt build first.

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


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

Then run from the command line:

Terminal window
npx staticbolt serve
# or using the alias
npx staticbolt preview

The server listens on http://localhost:4000 and serves the configured output directory. For the development server with file watching and live reload, use the dev command from developmentServerPlugin instead.

Command Options

--port <number>, -p

The port to listen on. Defaults to the plugin's port option.

--host

Listen on every address, so the site is reachable from other devices on the network.

--dir <path>, -d

The directory to serve. Defaults to the configured output directory.

--single, -s

Answer unknown paths with index.html, for a single page application.

--cors

Send Access-Control-Allow-Origin: * with every response.

--compress

Compress responses. On by default, turn it off with --no-compress.

Plugin Options

command

  • Type: string
  • Default: "serve"

The name of the CLI command to register.

serveCliPlugin({
  command: "preview-build",
});

aliases

  • Type: string[]
  • Default: ["preview"]

Other names that also run the serve command.

serveCliPlugin({
  aliases: ["preview", "static"],
});

port

  • Type: number
  • Default: 4000

The port the server listens on. --port overrides it for one run.

serveCliPlugin({
  port: 8080,
});

Behavior

When executed, the serve command:

  1. Resolves the directory to serve from --dir, the configured outdir, or ./dist
  2. Reports an error and exits with code 1 when that directory does not exist
  3. Starts a Fastify server over the files on disk

How it answers a request:

  • Responses are compressed with brotli or gzip, whichever the browser asks for. Files that carry their own compression, such as images and fonts, are sent as they are.
  • /about is answered with about/index.html, the way a static host does it. A missing page falls back to 404.html.
  • Everything is sent with no-cache, so a rebuild is never masked by a stale copy in the browser. Responses still revalidate with an ETag, so unchanged files come back as a 304.

See Also

This plugin usually goes last in the plugins array, next to the other CLI plugins. It does not take part in the build pipeline itself.