Configuration
Without configuration, the conventions apply: routes in src/pages/ (or src/
when it has no pages/ directory), output in dist/, public/ copied as is.
Add an ssg.config.ts at the project root when the site needs more:
import { defineConfig } from "@vincle/ssg";
export default defineConfig({
site: "https://example.com",
dev: {
notFound: "/404.html",
statuses: { "/404.html": 404 },
},
});
defineConfig only adds types. It also accepts a function, async or not,
receiving { command, mode }: command is "serve" under ssg dev and
"build" under ssg generate. The configuration is read at startup; restart
ssg dev after changing it.
Options#
| Option | Default | Description |
|---|---|---|
root |
current directory | Project directory; relative paths resolve from it |
src |
src/pages, otherwise src |
Directory of the routes |
out |
dist |
Output directory |
site |
none | Public origin, such as https://example.com; enables sitemap.xml |
base |
/ |
Path the site is served under, such as /docs/ |
sitemap |
true when site is set |
false disables sitemap.xml |
i18n |
none | { locales, defaultLocale }, for language alternates in the sitemap |
plugins |
[] |
Hooks into metadata, rendering and publication |
handlers |
built-in formats | Add a source format, or false to disable an extension |
runtime |
Vincle | Another JSX runtime and its renderer |
assets |
detected | Asset integrations: one, an array, or false; omitted detects Vite |
copy |
public/ |
More directories to copy, as { from, to? } |
preserve |
none | Top-level files of out that another tool owns |
dev holds the options of the development server alone:
| Option | Description |
|---|---|
notFound |
Page served for a missing URL, or a function of the decoded path |
statuses |
HTTP status per generated path, such as { "/404.html": 404 } |
redirects |
Path-to-path redirects |
mimeTypes |
Content type per extension, such as { ".md": "text/markdown" } |
vite |
Vite settings for the server only |
These mirror what the host does in production: see Deployment for the same settings on the host side.
Command line#
ssg <dev|generate> [options]
--config <file> Use a specific configuration file
--root <path> Project directory (default: current directory)
--mode <name> Configuration mode (default: development or production)
--port <number> Development server port (default: 4321)
--host <host> Development server address (default: 127.0.0.1)
The CLI looks for ssg.config with a .ts, .mts, .js, .mjs, .cts or
.cjs extension. It runs on Node; pages that use Bun APIs need
bun run --bun ssg generate. The same functions are exported for scripts:
import { build, dev } from "@vincle/ssg";
await build({ site: "https://example.com" });
const server = await dev();
server.vite.printUrls();
Assets#
assets accepts one AssetIntegration, an array, or false. Omitted, the
conventional detection applies (vite.config.*, otherwise
src/_client/main.*); assets: [] and assets: false both turn that detection
off — the difference is the intent, not the effect.
Every integration is prepared in its own directory tree, in declaration order,
and each rendered directory is copied to the root of out in that same order;
two outputs resolving to one path fail the build before publication. A relative
directory resolves from the project root. render wrappers chain in
declaration order, the first declared being the innermost (closest to the
page), and dispose runs for all of them in reverse order after publication,
best-effort. Only one integration may provide the module loader: two raise
INVALID_CONFIG. An integration declaring dev() is prepared once per session;
the others run prepare on every rebuild, and watch lists the files whose
modification rebuilds the site, so ssg dev honours the declared integrations,
not only Vite.
import { defineConfig } from "@vincle/ssg";
import { images } from "@vincle/ssg/image";
import { viteAssets } from "@vincle/ssg/vite";
export default defineConfig({
assets: [viteAssets(), images({ converter, descriptors: [portrait] })],
});
See Images for the image module.
Vite#
A vite.config.ts at the project root applies to the pages and the client
assets alike: aliases and plugins included. Set the base path with base in
the SSG configuration, not in Vite's: SSG passes it to Vite, and reports a
conflicting value. The Vite integration is one asset integration, the one
detected by default: declaring assets makes it explicit. Page compilation
always goes through Vite, even without a vite.config or client assets.
Plugins#
A plugin is an object with a name and up to four hooks, called in this order
for every build:
| Hook | Receives | Typical use |
|---|---|---|
metadata |
each page's context | Fill meta before layouts render |
render |
each output, not yet rendered | Wrap or replace how an output is produced |
transform |
each output, rendered | Rewrite the final text or bytes |
publish |
the whole site | Emit derived files, such as a search index |
import { defineConfig } from "@vincle/ssg";
export default defineConfig({
plugins: [
{
name: "default-title",
metadata(context) {
context.meta.title ??= context.route;
},
},
],
});
A hook that throws stops the build before dist/ changes, and the error names
the plugin and the hook.
Errors#
Every failure is an SsgError with a stable reason (such as
SOURCE_MISSING or INVALID_CONFIG), a message stating the problem and its
context, and a hint with the fix. JSON.stringify(error) gives the same
diagnostic as structured data. Test reason, never the message text.