@spacefast/vite-plugin

Vite integration for Spacefast routing conventions.

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

Install

npm install -D @spacefast/vite-plugin

Usage

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

export default defineConfig({
  plugins: [
    spacefast({
      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 Spacefast 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:

spacefast({
  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:

spacefast({
  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 Spacefast CLI:

npm run build
sf publish ./dist

Use sf publish ./dist --dry-run to validate the publish plan without uploading files.

TanStack Start

TanStack Start builds through several Vite environments and emits its static client output under dist/client. The tanstack-start entry point wraps spacefast() so that:

• the SSR build phase is allowed instead of rejected (allowSsrBuild),
• multiple Rollup inputs do not warn (allowMultipleInputs),
• the published directory prefers the client subdirectory of the output,
• SPA mode defaults to promoting TanStack's /_shell.html to /index.html and rewriting /* to it,
• server-only TanStack code leaking into client chunks produces a warning,
• routing convention files (_redirects / _headers) merge into the final client output after the last build phase.

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

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

For a fully client-rendered app, pass mode: "spa":

spacefastTanStackStart({ mode: "spa" });

All other spacefast() options (custom redirects, headers, publishDir, failOnRoutingError, ...) pass through unchanged.

Documentation

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