Vite and TanStack Start

Use the Stattic Vite plugins when a Vite build should behave like it will on Stattic during local development. The plugins are optional: Stattic can publish plain static build output without code changes. The plugin reads _redirects and _headers, supports inline rules in vite.config.ts, applies the same rules in the dev server, validates static-site output, and writes merged convention files into the build output.

Plain Vite

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",
    }),
  ],
});

Use mode: "static" for normal static sites. The build fails when Stattic cannot find generated HTML in the output.

TanStack Start static site

import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { statticTanStackStart } from "@stattic/vite-plugin-tanstack-start";

export default defineConfig({
  plugins: [
    tanstackStart({
      prerender: {
        enabled: true,
        failOnError: true,
      },
      spa: {
        enabled: false,
      },
    }),
    statticTanStackStart({
      mode: "static",
      redirects: ["/create /start 301", "/ai /ai.txt 200 Agent=true"],
    }),
  ],
});

This is the right model for marketing sites, docs, blogs, and product pages. TanStack can still build an internal server bundle for prerendering, but the deployed Stattic output must be static files.

TanStack Start SPA

import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { statticTanStackStart } from "@stattic/vite-plugin-tanstack-start";

export default defineConfig({
  plugins: [
    tanstackStart({
      prerender: {
        enabled: false,
      },
      spa: {
        enabled: true,
      },
    }),
    statticTanStackStart({
      mode: "spa",
      spa: {
        paths: ["/dashboard", "/dashboard/*"],
      },
      redirects: "/ai /ai.txt 200 Agent=true",
    }),
  ],
});

SPA mode generates rewrite rules for the configured paths. The default fallback is /index.html. TanStack Start emits its SPA shell as /_shell.html by default; the Stattic TanStack plugin moves that build artifact to /index.html so the output follows normal static-hosting conventions.

Rule sources and merge order

You can define routing in Vite config, root _redirects and _headers, public/_redirects and public/_headers, or a configured publish directory.

For _redirects, Vite config rules are written first, file rules next, and generated SPA fallback rules last so explicit app behavior wins first-match conflicts. For _headers, file rules are written before Vite config rules so config can override later. The output files include a generated header comment and are written to the deployable output directory.

Build summary

Each build prints a Stattic routing summary with the mode, redirect sources, header sources, and files written. Use it to confirm which rule source produced the final _redirects and _headers.

Inspect routing locally

After a build, inspect the generated output:

stattic inspect --routing dist --url /dashboard

The command prints compiled rule counts, diagnostics, and match results for each URL.