vSsg

Static site generator. MDX + React component routes in, deterministic HTML out. Pipeline of stages: parse routes, compile MDX, render to HTML, extract semantic classes, emit HTML/Liquid. Build-time only; no watch mode, no dev server.

Install

npm install @booga/vssg

Peer dep: react ^18.

Usage

import { generate, defineConfig } from "@booga/vssg";

const config = defineConfig({
  srcDir: "./src",
  outDir: "./dist",
  routes: "routes/**/*.mdx",     // glob or () => RouteEntry[]
  targets: ["html", "liquid"],   // default: ["html"]
  publicDir: "./public",
  baseUrl: "/",
});

const result = await generate(config);
// { pages: number, assets: string[], durationMs: number }

Pipeline

parseRoutes → compileMdx → render → extractSemantic → emitHtml → emitLiquid

Each stage is a { name: string; run: (ctx: PipelineCtx) => Promise<PipelineCtx> }. Insert custom stages by passing a stages array as the second argument to generate().

Semantic CSS

Components using @booga/vdsl DSL props emit data-class attributes. The extractSemantic stage collapses these into stable .block-<hash> classes and writes semantic.css with @apply rules for Tailwind to resolve.

Targets

• "html" — writes <route>.html + semantic.css to outDir.
• "liquid" — writes <route>.liquid templates referencing .block-* classes.

API

Export	Type	Description
generate(config, stages?)	Promise<GenerateResult>	Main entrypoint. Validates config, runs pipeline.
defineConfig(config)	SsgConfigInput	Type helper. Identity function.
defaultStages	Stage[]	The six built-in pipeline stages.
SsgConfigSchema	Zod schema	Runtime config validation.
SsgConfig	type	Resolved config (defaults applied).
SsgConfigInput	type	User-facing input config (defaults optional).
Stage	type	{ name: string; run: (ctx) => Promise<ctx> }
GenerateResult	type	{ pages, assets, durationMs }

Code of Conduct

Contributor Covenant 2.1 — https://www.contributor-covenant.org/version/2/1/code_of_conduct/