@stattic/vite-plugin-tanstack-start

TanStack Start integration for publishing static and SPA builds to Stattic.

This package wraps @stattic/vite-plugin with TanStack Start defaults so the generated client output is ready for Stattic routing validation and publishing.

Install

npm install -D @stattic/vite-plugin-tanstack-start

Usage

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

Static mode

Use mode: "static" for fully prerendered TanStack Start sites. TanStack may build an internal SSR bundle to prerender pages, but Stattic deploys only the generated static client output.

SPA mode

Use mode: "spa" for TanStack Start apps that ship a client shell:

statticTanStackStart({
  mode: "spa",
  spa: {
    paths: ["/dashboard", "/dashboard/*"],
  },
});

The default SPA fallback is /index.html. TanStack Start emits its SPA shell as /_shell.html by default; this plugin moves that build artifact to /index.html before validation so the deployable output matches normal static-hosting conventions. The plugin also generates fallback rewrites and writes merged _redirects and _headers into dist/client.

File-based _redirects and _headers still work, but first-party app behavior is usually clearer in vite.config.ts.

Publish

Build the app, then publish the static client output:

npm run build
npx stattic-cli publish ./dist/client

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

Documentation

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