@stattic/vite-plugin

Vite integration for Stattic routing conventions.

Use this plugin when your Vite app will be published to Stattic and you want local development, build output, and version validation to agree on routing behavior.

Install

npm install -D @stattic/vite-plugin

Usage

import { defineConfig } from "vite";
import { stattic } from "@stattic/vite-plugin";

export default defineConfig({
  plugins: [
    stattic({
      mode: "static",
      redirects: ["/old /new 301"],
      headers: "/*\n  x-frame-options: DENY",
    }),
  ],
});

What it does

• Reads _redirects and _headers from the space root, Vite publicDir, and optional publishDir.
• Accepts inline redirects and headers in Vite config.
• Applies Stattic redirects, rewrites, proxy rules, Basic-Auth, and headers in the Vite dev server.
• Writes merged _redirects and _headers into the build output.
• Validates that the build is deployable as static files.
• Prints a routing summary after build.

Modes

Use mode: "static" for prerendered or normal static sites. The plugin requires HTML in the build output.

Use mode: "spa" for client-rendered apps. The plugin generates fallback rewrite rules and validates that the fallback file exists:

stattic({
  mode: "spa",
  spa: {
    fallback: "/index.html",
    paths: ["/app", "/app/*"],
  },
});

If a framework emits the SPA shell under a different filename, set spa.fallbackSource. The plugin moves that file to the configured fallback before validating the build:

stattic({
  mode: "spa",
  spa: {
    fallback: "/index.html",
    fallbackSource: "/_shell.html",
  },
});

Merge order

For _redirects, config rules come first, file rules come next, and generated SPA fallback rules come last. Redirects are first-match wins, so explicit app behavior wins before the fallback.

For _headers, file rules come before config rules. Header rules are applied in order, so config can override file headers.

Generated output files start with a comment so it is clear they came from the plugin.

Publish

Build your site, then publish the generated output with the Stattic CLI:

npm run build
npx stattic-cli publish ./dist

Use npx stattic-cli publish ./dist --dry-run to validate the publish plan without uploading files.

Documentation

• Stattic docs
• CLI docs
• Vite integration docs
• Redirects
• Headers
• Agent setup
• LLM guide