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/