Skip to main content

@ovineko/spa-guard-vite

Vite plugin for spa-guard — injects the runtime inline script and loading spinner into your SPA's HTML at build time.

Install​

pnpm add -D @ovineko/spa-guard-vite
pnpm add @ovineko/spa-guard

Usage​

Add the plugin to your vite.config.ts:

import { spaGuardVitePlugin } from "@ovineko/spa-guard-vite";
import { defineConfig } from "vite";

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

With options:

export default defineConfig({
  plugins: [
    spaGuardVitePlugin({
      version: "1.0.0",
      reloadDelays: [1000, 3000, 10000],
      html: { spinner: { background: "#f5f5f5" } },
    }),
  ],
});

Disable the spinner:

spaGuardVitePlugin({ html: { spinner: { disabled: true } } });

Enable trace mode (logs extra debug info at runtime):

spaGuardVitePlugin({ trace: true });

Use external script mode to write a content-hashed .js file instead of inlining the script:

spaGuardVitePlugin({
  mode: "external",
  externalScriptDir: "dist/assets",
  publicPath: "/assets",
});
// Injects <script src="/assets/spa-guard.abc12345.js"> into the HTML

Options​

VitePluginOptions extends the core Options type and adds:

OptionTypeDefaultDescription
mode'inline' | 'external''inline'Inject script inline or write an external file
externalScriptDirstring—Output directory for external mode (e.g., dist/assets)
publicPathstring'/'Public path prefix for the generated script URL
versionstringauto UUIDVersion string for cache busting
reloadDelaysnumber[]—Retry delay sequence in ms
useRetryIdboolean—Append retry ID to chunk URLs
html.spinner.disabledbooleanfalseDisable loading spinner injection
html.spinner.contentstringbuilt-in SVGCustom spinner HTML content
html.spinner.backgroundstring"#fff"Spinner overlay background color
html.fallback.contentstring—Fallback HTML shown on error (auto-minified)
tracebooleanfalseUse trace build with debug logging

What the plugin injects​

In inline mode (default):

  • A <script> in <head> (prepended) containing the full spa-guard runtime inline

In external mode (mode: 'external'):

  • A <script src="..."> in <head> (prepended) referencing the content-hashed file
  • The content-hashed .js file is written to externalScriptDir (or Vite's build.outDir) during the bundle step

In both modes:

  • A spinner <div> in <body> (prepended) that hides until your app loads
  • A <script> to set overflow: hidden while loading
  • A <style> for the spinner background CSS variable (only when background differs from #fff)