Skip to main content
View as Markdown

Templates & Examples

The fastest way to learn Sovrium is to start from a working app. Sovrium ships a set of example configurations — each a complete, runnable project that composes real features (tables, auth, pages, theme, i18n, automations) into a single config tree. The same examples double as sovrium init templates, so you can scaffold any of them into a new directory and start iterating immediately.

Every example is a directory with an app.yaml entry point. Anything beyond the smallest starter splits its configuration across a config/ subtree using $ref — one file per collection entity, one file per singleton, scalars stay inline. This mirrors the structure sovrium init scaffolds for you.

Available templates

Template Description
hello-world Minimal starter — one page, no collections. The default for sovrium init. Stays a single app.yaml to demonstrate when not to pre-split.
landing-page Bilingual marketing site with i18n, a theme, reusable components, and the home page split out for size.
crud-app CRUD app with tables (contacts, companies), email/password auth, a theme, and dashboard + sign-in pages.
api-only Headless API mode with tables (projects, tasks) and auth — no pages. Demonstrates Sovrium as a backend.
member-portal Public marketing pages plus an auth-gated portal area with role-gated sections. Magic-link + password auth.
mcp-server Headless MCP server exposing tables to an LLM client via per-entity aiAccess — no pages. See MCP Integration.
blog Blog with posts (rich-text), tags, authors, and an index plus a dynamic /blog/:slug detail route.
docs-site Documentation website showcasing the markdown-pages feature: real .md files under content/docs/, a contentDir collection, a frontmatter sidebar, prev/next chrome, a TOC, and Shiki-highlighted code. No tables, no auth.

Several templates ship with a paired editor agent (a Claude Code subagent definition) that sovrium init installs into .claude/agents/. See sovrium agents for managing agent templates directly.

Scaffolding a project

sovrium init copies a template into a new (or current) directory. With no --template, the minimal hello-world starter is used.

# Default (hello-world, no paired agent)
sovrium init my-app

# Choose a template — also installs the paired editor agent
sovrium init my-app --template crud-app
sovrium init my-app --template landing-page
sovrium init my-app --template blog
sovrium init my-app --template member-portal

# Skip the paired agent install
sovrium init my-app --template crud-app --no-agent

Then run the scaffolded app:

sovrium start app.yaml          # Start the dev server
sovrium validate app.yaml       # Validate without starting

See the CLI Reference for all init flags.

Anatomy of an example

A non-trivial example looks like this (abbreviated crud-app layout):

crud-app/
├── app.yaml                 # Entry point — references everything via $ref
├── config/
│   ├── auth.yaml            # Singleton: auth strategies, roles
│   ├── theme.yaml           # Singleton: design tokens
│   └── tables/
│       ├── companies.yaml   # One file per table
│       └── contacts.yaml
└── public/                  # Static assets (favicon, images)

The app.yaml entry point pulls each part together with $ref, keeping the top-level file small and each entity in its own file:

name: crud-app

auth:
  $ref: ./config/auth.yaml

theme:
  $ref: ./config/theme.yaml

tables:
  - $ref: ./config/tables/companies.yaml
  - $ref: ./config/tables/contacts.yaml

pages:
  - $ref: ./config/pages/dashboard.yaml
  - $ref: ./config/pages/sign-in.yaml

$ref resolution happens before validation: any object containing exactly one key — $ref whose value is a relative path — is replaced with the parsed contents of that file. A $ref may itself contain further $refs, so configs nest to any depth. The single-file and multi-file forms are interchangeable; pick whichever keeps the project readable.

Learning path

A practical order for working through the examples:

  1. hello-world — understand the minimal shape of a config and the pages array.
  2. landing-page — add a theme, reusable components, and i18n with $t: translation keys.
  3. crud-app — introduce tables, auth, and data-bound pages (forms + data tables).
  4. api-only / mcp-server — run Sovrium headless: as a REST backend or an LLM-facing MCP server.
  5. blog / member-portal / docs-site — combine dynamic routes, role-gated areas, and markdown content.
  • Quick Start — zero to running app via YAML + CLI or TypeScript + Bun.
  • Configuration Files — YAML, JSON, TypeScript, and $ref multi-file composition.
  • CLI Reference — sovrium init, sovrium agents, and the full command surface.
  • MCP Integration — the headless MCP-server template explained.