@gusnips/vite
Turn a Vite + React SPA's public routes into real HTML files at build time: a real <head>, a
real body, one file per page.
bun add -d @gusnips/vite
import { pageFile } from "@gusnips/vite";
pageFile("/pricing"); // → "pricing.html"
Why bother
A Vite SPA ships one index.html and draws everything else with JavaScript. Nothing that reads a
link for a living runs that bundle: not a search crawler, not an LLM, not the thing that draws
the preview card when someone pastes your link in a chat. A shipped <div id="root"></div> is a
page that can be listed and never quoted.
So the build renders each public route to its own file. This is the part every app doing that ends up writing.
Baking a page
import { bakeHead } from "@gusnips/vite";
const html = bakeHead(template, {
title: "Pricing | Example",
description: "What it costs.",
canonical: "https://example.com/pricing",
body: { route: "/pricing", html: rendered },
});
bakeHead rewrites the title, the description, the canonical, the Open Graph and Twitter tags,
<html lang>, the hreflang set, and injects the rendered markup into <div id="root">.
Four rules in there are load-bearing:
canonical: nullstrips the tag, andog:urlwith it. For the 404 shell, which is served for every address that does not exist. Blanking is not stripping: an empty canonical is a claim about"", and an emptyog:urlis a card pointing at your front page. Leaveimageout there too, and the shell keeps the card your template already has. The image is the half people miss, andbakeHeadcannot catch it for you. It writes whatever card you name. Three codebases named the shell's card after its made-up path, so their404.htmladvertised/og/__not-found__.png, a file that has never existed. Every share of a dead link unfurled broken, and nothing in a browser showed it.og:localeis not optional on a non-English page. Leave it out and the spec does not default it to "unknown". It defaults toen_US. A Portuguese page with a Portugueseog:titlethen tells every share crawler the card is English.ogLocale("pt-BR")gives you the underscore spelling it actually wants.bodycarries the route, not just the markup. A static host answers every address it does not publish with the nearest404.html, and that file has the not-found page rendered into it. So "does the root have children" is the wrong question: a route served from the shell finds a full root, hydrates, and React reconciles two different pages. It recovers by throwing the tree away and logging: a page that works, and a bug nobody sees. The marker is what the browser entry compares against before it decides.alternatesmust be reciprocal. A crawler ignores the whole set unless every address in it points back at the others, which is why you pass the full list to every page rather than "the other two".
Discovery files
import { jsonLd } from "@gusnips/vite";
jsonLd({ "@type": "SoftwareApplication", name: "Example" });
// A <script type="application/ld+json"> tag containing the object.
Pass the result to bakeHead as headExtra. jsonLd escapes HTML control text while keeping
valid JSON. faqJsonLd uses the same serializer. You supply the schema.org fields, including
SoftwareApplication for an app or WebAPI for a public API. A local command is not a public API.
import { llmsTxt, mcpDiscoveryJson, writeDist } from "@gusnips/vite";
await writeDist(
"dist",
"llms.txt",
llmsTxt({
title: "Example",
summary: "Read and update tasks.",
sections: [
{
title: "Reference",
links: [{ title: "Connect", url: "https://example.com/docs/mcp" }],
},
],
}),
);
await writeDist(
"dist",
"llms-full.txt",
llmsTxt({
title: "Example reference",
body: referenceMarkdown,
}),
);
await writeDist(
"dist",
".well-known/mcp.json",
mcpDiscoveryJson({
name: "Example",
homepage: "https://example.com",
documentation: "https://example.com/docs/mcp",
llmsTxt: "https://example.com/llms.txt",
llmsFullTxt: "https://example.com/llms-full.txt",
servers: [
{
name: "tasks",
transport: "streamable-http",
url: "https://api.example.com/mcp",
authentication: [
{
type: "oauth2",
protectedResourceMetadata:
"https://api.example.com/.well-known/oauth-protected-resource/mcp",
},
],
tools: ["list_tasks", "update_task"],
},
],
}),
);
Build referenceMarkdown from your existing docs. The formatter adds no content or access rules.
Each server lists only its own tools, as names or objects with name, title, description,
inputSchema and annotations. Supplied schemas and annotations are kept unchanged.
For a local server, use transport: "stdio", command and optional args instead of url.
authentication is a list of accepted methods: oauth2 with protectedResourceMetadata, api-key
with in (header or environment), name and optional prefix, session with a description,
or none for public access. Methods can also include description and documentation.
/.well-known/mcp.json is discovery metadata, not a universal MCP standard or a client config.
It does not replace the live server's tools/list. These files do not promise search rankings or
support in a particular client.
Rendering
import { renderTree } from "@gusnips/vite/render";
Behind its own subpath, because it is the one thing here that loads React. A repo that only wants a sitemap installs no renderer.
Your SSR entry exports a function named renderPage that calls it. The prerender script loads it
with loadRenderer("dist-ssr/entry-server.js"), which looks for that name and stops the build if
it is not there.
It uses prerender from react-dom/static, never renderToString. With lazy() routes behind
a <Suspense>, renderToString renders the fallback. It will write a loading screen into
every file and pass any gate that only asks whether the root has children. It also answers ""
for a basename mismatch with no error and no warning, so assertRendered checks every route for
non-empty output. And React 19 hoists in-tree <title> and <meta> to the front of the server
stream, which lands them inside your body when you are filling one <div> rather than assembling
a document, so those get stripped, and a render error is rethrown so a broken page fails the
build instead of shipping.
The fallback is not the worst case. renderToString can write its own ERROR into the page: one
repo shipped a live, indexed reference page carrying React's "does not support Suspense" message,
a stack trace, and five copies of an absolute path from the machine that built it. Nothing in a
browser shows it, because the bundle replaces the body on load, so the only readers who ever saw
it were the ones who run no JavaScript, which is every crawler the page was built for. It was in
one of its two languages, too: the first render bails but resolves the lazy() promise, so the
next locale rendered the real component and looked perfect. assertRendered refuses that text now.
Call assertRendered(file, html, template) on every page before you write it. It stops the build
when:
- the page is less than 500 bytes bigger than
index.html. A page that is short on purpose passes a lower floor:{ minGrowth: 200 }. - the
<title>is empty, or, when you pass{ lang },<html lang>names another language. - a
%NAME%placeholder was never filled in. - React's
renderToStringerror is in the page. - the page is the loading screen. It knows one only by
role="status", so give your Suspense fallback that role, which a screen reader needs anyway. A plain<p>Loading…</p>passes.
End your prerender script with process.exit(0). Under bun, importing this renderer leaves the
process alive after the last file is written: react-dom/server exits, react-dom/static.browser
does not, and process.getActiveResourcesInfo() shows nothing either way, so the only symptom is a
script that finishes its work and never returns. Node 26 does the same (measured with react-dom
19.3). We do not call exit for you (a library killing its host process is worse than the hang),
and in CI the alternative is a job that builds everything and then runs to its timeout.
Flat files
That pageFile at the top writes pricing.html, not pricing/index.html. Nested routes keep
their folders: /guides/errors → guides/errors.html.
Every address your app puts in a canonical or a sitemap has to answer 200 rather than redirect. On
Cloudflare Pages that means flat files: it serves pricing/index.html at /pricing/ and answers
/pricing with a 308. A flat file answers /pricing with a 200 and normalizes /pricing/ to it
with a 308, so the form you advertise is the form that is a page, which is the whole point.
This page said "a flat file answers both" until somebody ran the curl -I the next paragraph asks
for: /precos/ came back 308, location: /precos. Nothing about the rule changed, but the
detail matters when you are deciding whether a slash-tolerant hydration check is fixing anything:
on a host that normalizes, the browser is redirected before your bundle runs, so it never can.
Hosts differ, though. Firebase Hosting redirects /pricing to /pricing/ by default, and serves
pricing/index.html at /pricing itself once trailingSlash is false. On a host like that,
write the directory form and set the flag. Either way, run curl -I on one page before you trust
the sitemap.
Sitemap, robots, OG cards
sitemapFor(origin, pages) walks your page registry; robotsTxt({ origin, sitemaps }) generates
the file, listing every sitemap in one, because a crawler only reads the one at the origin root:
a subdirectory app cannot ship its own.
sitemapXml takes priority pre-formatted, as a string. Ranking pages is a decision that
belongs to whoever walks the registry: one codebase reads a field off its own registry, another
gives the front door 1.0 and every guide 0.8 flat, because ranking one guide above another would
be a guess about a reader.
writeOgCards walks the registry and calls a renderer you supply, and fitText does the
text-fitting maths. When copy does not fit, it records the overflow and refuses to write
rather than appending an ellipsis: an ellipsis makes every string "fit", so copy that outgrew
its column has no failing case and ships.
assertOgImages("dist", origin) reads every page the build wrote and checks that each share card
it advertises is a file that exists. Run it last:
await assertOgImages("dist", "https://example.com");
Three codebases shipped a 404.html whose og:image named a card nothing had ever rendered:
the card generator walks the page registry, and a not-found shell is not in it. Every share of a
dead link unfurled broken, and nothing in a browser shows it. bakeHead cannot catch this: it
writes the image it is handed, and a shell carrying the brand card is correct. The build can,
because by then the card is on disk or it is not. Cards on another host are skipped.
loadTemplate refuses a dist/index.html that is already a rendered page. dist/index.html is
both the file every page is baked from and the home page's own output, so a second pass over a
written dist/ reads a finished page as its blank and nests one render inside another. vite build empties dist/ and normally makes that impossible: a restored build cache and a hand-run
of the script both route around it.
Theme before the first frame
import { themeScript } from "@gusnips/vite/theme";
export default defineConfig({ plugins: [themeScript({ key: "app.theme" })] });
Writes assets/theme-<hash>.js and one <script src> at the end of <head>, so the page is
painted in the reader's theme before anything else runs. The file is the source of startTheme
from @gusnips/react/theme, so the script before paint and the controller the app uses are
the same function. It is a file rather than an inline script so a script-src 'self' policy
lets it run. Pass it the same options you pass createTheme; see that package's README. On
the preset, put it in plugins.
themeScript is built on prePaintScript, which takes any script that has to run before the
page shows. @gusnips/locale's localeGateScript is the other one:
import { prePaintScript } from "@gusnips/vite";
prePaintScript({ name: "locale", source: localeGateScript({ ... }), position: "head-prepend" });
The script runs on its own, before your bundle, so it must not use anything outside itself. The
tag goes at the end of <head> by default. position: "head-prepend" puts it first instead, so
it does not wait for your stylesheets to download. Use that for a script that may leave the page.
Check your translations
// scripts/check-i18n.ts
import { readFile } from "node:fs/promises";
import { checkI18n, formatI18nReport, type I18nBundle } from "@gusnips/vite/i18n";
const web: I18nBundle = {
name: "web",
locales: ["en", "pt-BR", "es"],
canonical: "en",
load: async (locale) => ({
translation: JSON.parse(await readFile(`src/i18n/locales/${locale}.json`, "utf8")),
}),
};
const report = await checkI18n([web]);
console.log(formatI18nReport(report));
process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
Your canonical language is typed, so a t("key") it lacks already fails to compile. The other
languages are not, and neither is anything inside a string. This checks what the compiler can't:
| It fails when | Because the reader gets |
|---|---|
| a key is in one language and not another, or is blank | the canonical language, in the middle of their own |
a counted key lacks a form its language needs (pt _many) | the fallback language at exactly 1,000,000, or the raw key |
{{name}} became {{nome}}, or {{n, number}} lost number | a gap, or 5000 where they write 5.000 |
<0>…</0> is out of order or not closed | the wrong words bold, or the tag as text |
a placeholder is named lng, ns or another t() option | another language, not the value |
| a language fails to load | nothing: every other rule would have passed it empty |
load returns one language's catalogs by namespace, so JSON files, TS modules and a runtime
merge all fit. If it throws, the check fails with the error. It never skips.
Give it code and it reads your source too: every static t("key") exists, a template key's
fixed start exists (t(`plan.${id}.title`) needs plan), <Trans> has no children (they
shift every <0>), and copy with <strong> in it is not read through t(), which prints the
tag as text.
await checkI18n([{ ...web, code: ["src/**/*.{ts,tsx}"] }]);
Keys the server sends are shown in whatever language the reader has, so each one must be in every
language. Pass the list if you can import it, or the server's source to scan for messageKey::
await checkI18n([{ ...web, serverKeys: MESSAGE_KEYS }]);
// or, with no list to import:
await checkI18n([
{ ...web, serverCode: ["apps/api/src/**/*.ts"], serverKeyPrefixes: ["serverErrors."] },
]);
The scan reads text, not syntax, so a t("key") inside a comment counts too, and fails the check
if the key is gone. Fix the comment. Skipping comments safely would take a full parser: a pattern
that cuts a line at // also cuts it at https://, and would quietly miss a real t() after it.
report.unused lists canonical keys no code seems to reach. It is a hint, not a failure: a key
built at runtime from a variable can't be seen by a scan.
If your prices come from a formatter, pass { price: /\$\s?\d/ } as the second argument and a
price typed into copy fails too.
Fragments. If several people write screens at once, keep one file per area with every
language side by side ({ "en": {…}, "pt-BR": {…} }) and merge them. writeFragments writes
out/<locale>.json with sorted keys, so two runs write the same bytes, and writes nothing if two
fragments disagree. The check then fails if a committed catalog no longer matches its fragments:
await checkI18n([{ ...web, fragments: { dir: "src/i18n/fragments", out: "src/i18n/locales" } }]);
If the app merges fragments at runtime with a spread ({ ...auth.en, ...nav.en }), leave out
off and set ownTopLevel: true. A spread keeps only the second of two fragments that share a
top-level key, so that is refused.
Check your contrast
// scripts/check-contrast.ts
import { checkContrast, formatContrastReport } from "@gusnips/vite/contrast";
const report = await checkContrast([
{ name: "web", entry: "src/index.css", sources: ["src/**/*.{ts,tsx}"] },
]);
console.log(formatContrastReport(report));
process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
The tokens package measures the placeholder colours it ships. This measures yours: it compiles your entry with the real Tailwind CLI and reads the CSS that comes back. No Tailwind? The next section reads plain CSS custom properties instead.
| It fails when | Because the reader gets |
|---|---|
--color-input is under 3:1 on --color-background, either mode | a field border some people cannot see |
--color-foreground is under 4.5:1 on the background, either mode | body copy some people cannot read |
--color-primary is the same fill in both modes | a control that lands on the 3:1 line at night |
a token has no value in .dark | one mode keeping the other mode's colour |
a class paints from a colour your @theme never declares | text-white reading right at noon and vanishing at night |
A floor it cannot measure fails too: a value that is not a hex colour (or a var() chain to
one) is a floor nobody is keeping. State variants are held to the same token rule, and a
hover: that paints the same fill the base already has is a warning, so the state changes
nothing. A class that compiles to no rule at all is a warning as well: a token Tailwind does
not have, or a class built dynamically that no scan can see.
Pass allow: [/^bg-brand-/] for the classes a repo means. Floors take no allow list: a
measured ratio is not a judgement call.
Check your contrast without Tailwind
If your colours are plain CSS custom properties, there is no @theme to compile. Name the file,
the selector of the dark block, and the pairs that must stay readable:
// scripts/check-contrast.ts
import { checkTokenPairs, formatContrastReport } from "@gusnips/vite/contrast";
const report = await checkTokenPairs([
{
name: "site",
css: "src/tokens.css",
dark: ':root[data-theme="dark"]',
textPairs: [["--ground", "--ink"]],
},
]);
console.log(formatContrastReport(report));
process.exit(report.problems.some((p) => p.level === "error") ? 1 : 0);
It reads the colours in :root { … } as the light theme and the colours in your dark block as the
dark one. A product with no dark theme leaves dark off: each pair is then measured once, in the
light block, and no token needs a dark twin. If --ink on --ground is under 4.5:1 in either, it prints the line and exits 1:
site
✖ floor: src/tokens.css:8 dark: --ink (#3a3a3a) on --ground (#121212) is 1.65:1, under the 4.5:1 floor for text (WCAG 1.4.3)
✖ contrast: 1 error(s)
Nothing is compiled, so it needs no Tailwind and no other peer. It returns the same report as
checkContrast, so the formatter is the same, and you can join the two before you exit:
report.problems.push(...other.problems).
| It fails when | Because the reader gets |
|---|---|
| a pair is under its floor in the light or the dark theme | text or a border some people cannot see |
| a colour is in one theme and not the other | one mode keeping, or lacking, a colour |
| a pair names a token that no block declares | a typo that looks like a pair that passes |
| a pair holds a colour that is not hex | a floor nobody is keeping |
the system block differs from the dark block, or is not in the @media | a page with no saved choice that looks different |
textPairs are held to 4.5:1 and nonTextPairs (borders, focus rings, icons) to 3:1. Change
them with textFloor and nonTextFloor. A pair is [background, foreground]; the ratio is the
same either way round, so the order only decides how the message reads. Write the names as the CSS
does, with the --. The light block is :root unless you set light.
The system block. A page that has not chosen a theme follows the system, so many apps write the dark colours twice: once for the chosen theme and once for everyone else.
:root {
--ground: #ffffff;
--ink: #1a1a1a;
}
:root[data-theme="dark"] {
--ground: #121212;
--ink: #f2f2f2;
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme]) {
--ground: #121212;
--ink: #f2f2f2;
}
}
Pass system: ":root:not([data-theme])" and the check holds the second block to the first: the
same tokens, the same colours (#FFF and #ffffff are the same colour), and inside
@media (prefers-color-scheme: dark). Either dark block can sit inside @media screen { … }.
Your own checks. loadTokenThemes hands back the two palettes as hex, with the same file and
selectors:
import { loadTokenThemes } from "@gusnips/vite/contrast";
const { light, dark } = await loadTokenThemes({
css: "src/tokens.css",
dark: ':root[data-theme="dark"]',
});
light.get("--ground"); // "#ffffff"
Use it for what only your app knows: that the browser's toolbar colour is the page's ground in each theme, for example. It throws, and says what is missing, if the file or a block is not there.
What it does not read. It reads text, not CSS, and there is no CSS parser behind it.
- Only hex colours (
#fffor#ffffff) are measured. A token in a pair that holdsrgb(),oklch()orvar()fails as one it cannot measure. Tokens no pair uses, like--radius, are left alone. - A block is found by its selector text, inside any
@media, and must hold declarations only. A block with another rule inside it (nested CSS) is not read, and the check says it found no block. - A media query is read, not run. A
@media printblock with your dark selector counts as that selector. If one selector is written twice, the later token wins, as it does in CSS. - Light and dark need different selectors.
The vite preset
import { webPreset } from "@gusnips/vite/preset";
import { defineConfig } from "vite";
export default defineConfig(webPreset({ root: import.meta.dirname, port: 5173 }));
It adds the React and Tailwind plugins, points @ at src, and runs vite preview on the port
minus 1000. root is required: it is the folder that holds index.html. Its own subpath too,
since it pulls in those two plugins.
Pass more plugins in plugins. They run after the preset's own:
export default defineConfig(
webPreset({ root: import.meta.dirname, port: 5173, plugins: [themeScript(THEME)] }),
);
MIT · part of kit