Building a static site
A component that renders the same HTML for every visitor does not need a
server. Render it once, at build time, and publish the files: any static host
or CDN serves them, and there is nothing to keep running. @vincle/ssg does
this for a whole directory of pages.
Start a project#
Follow Installation, add the generator and its two commands:
npm install @vincle/ssg
pnpm add @vincle/ssg
bun add @vincle/ssg
{
"scripts": {
"dev": "ssg dev",
"build": "ssg generate"
}
}
Write the layout once#
Every page shares the document around it. Put it in src/_layout.tsx: the
leading _ keeps it from becoming a page.
import { raw, type JSX } from "@vincle/core";
import type { SsgMeta } from "@vincle/ssg";
export default function Layout({ children, meta }: { children: JSX.Element; meta: SsgMeta }) {
return (
<>
{raw("<!DOCTYPE html>\n")}
<html lang="en">
<head>
<meta charset="utf-8" />
<title>{meta.title ? `${meta.title} · Acme` : "Acme"}</title>
</head>
<body>
<nav>
<a href="/">Home</a> <a href="/products">Products</a>
</nav>
<main>{children}</main>
</body>
</html>
</>
);
}
Load data at build time#
Pages are the components you already write, and they can be async. The data is read during the build: the published page holds the result, not the query.
declare function listProducts(): Promise<{ name: string; price: number }[]>;
export const meta = { title: "Products" };
export default async function Products() {
const products = await listProducts();
return (
<ul>
{products.map((product) => (
<li>
{product.name}: {product.price.toFixed(2)} €
</li>
))}
</ul>
);
}
src/pages/products.tsx becomes /products. Data that changes between two
builds shows up at the next build: rebuild when the data changes, or keep the
page on a server.
Write content in Markdown#
Pages made of prose read better as Markdown. The same layout wraps them, and
the frontmatter plays the part of meta:
---
title: About
---
# About Acme
We have been making things since 1998.
Need a component in the middle of the text? Rename the file to .mdx and
import it.
Preview, then publish#
npm run dev serves the site on http://127.0.0.1:4321 and reloads the page
on every change. npm run build writes dist/: copy that directory to any
static host. Until the build succeeds, dist/ keeps the previous version.
When a page cannot be static#
A page that depends on the visitor or on the latest data belongs on a server:
render it per request with renderToString, as in
From a view to progressive HTML. Both kinds of page use the
same components.
Where to next#
- SSG overview: conventions and URLs
- Pages & layouts: formats, metadata, client assets
- Deployment: server configuration per host