REDWEBAPI guide

defineSite

Documentation for Redweb 0.13.3. Install that exact version when following these examples.

Defines shared static-site CSS, metadata, caching, layout, canonical URLs, and export behavior once. Site pages are always runtime-free.

Explain it like I’m five

defineSite is the shared blueprint for a collection of pages: one place for the frame, colors, metadata, cache policy, canonical links, and export rules.

When should I use it?

Use it for documentation, marketing, or content sites where many runtime-free pages should share layout and production behavior.

Follow the example

This API pattern illustrates the named surface; it may require application-owned classes, credentials, or assets. Start from a complete recipe for a runnable application.

tsx
import { defineSite } from 'redweb'

const docs = defineSite({
  origin: 'https://example.com',
  css: 'site.css',
  head: { description: 'Product documentation', image: '/og.png' },
  cache: { maxAge: 300 },
  layout: content => <body><nav>Product</nav><main>{content}</main></body>,
})

@docs.page('/docs', { head: { title: 'Documentation' } })
class DocsPage {
  render() { return <h1>Documentation</h1> }
}

await docs.export(DocsPage, {
  outDir: 'dist',
  publicDir: 'public',
})
  1. The site definition establishes origin, common CSS, head metadata, cache policy, and layout.
  2. Decorated pages contribute their own route, title, description, and stylesheet.
  3. site.export stages every page and asset into one consistent static output.

Options

  • origin: optional HTTP(S) origin used to derive canonical and root-relative social-image URLs
  • css, head, cache, and layout: defaults inherited by every site.page() decorator
  • layout: synchronous function receiving the trusted page fragment and portable request context
  • publicDir: optional link-free asset tree staged with generated output

Methods and members

site.page(path, options?)

Creates a non-live page decorator while merging shared defaults and page-specific overrides.

site.export(pageOrPages, options)

Stages all pages and public assets, rejects path collisions, then writes the destination and returns every output path.

What should I watch for?

The layout must handle every exported route. Keep route-specific chrome derived from stable metadata rather than scattered path checks.