TypeScript API

Use Sovrium as a library in your TypeScript project. Import start, build, and the AppConfig type for full programmatic control with typed configuration.

TypeScript

import { start, build } from 'sovrium'
import type { AppConfig, SimpleServer } from 'sovrium'

// All config types are available:
// PageConfig, TableConfig, ThemeConfig, AuthConfig,
// ComponentConfig, LanguageConfig, AnalyticsConfig, ...

Why TypeScript?

Using Sovrium programmatically gives you advantages beyond the CLI.

Type safety

The AppConfig type provides autocomplete for every property and field type. Catch errors at compile time, not runtime.

Programmatic control

Generate configuration dynamically, compose schemas, and integrate Sovrium into existing applications.

IDE integration

Full IntelliSense in VS Code and JetBrains — hover docs, go-to-definition, and type errors.

start(app, options?)

Start a development server from a typed configuration object. Returns a server instance with a stop() method.

TypeScript

import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)

StartOptions

Optional second argument to configure the server.

PropertyDescription

portPort number (0–65535). 0 selects an available port. Default: 3000.

hostnameServer hostname. Default: localhost.

publicDirStatic file directory. Files are served at their relative path.

TypeScript

import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)

build(app, options?)

Generate a static site from a typed configuration object.

GenerateStaticOptions

Optional second argument to control static output.

PropertyDescription

outputDirOutput directory. Default: ./static.

baseUrlBase URL for sitemap and canonical links.

basePathPath prefix for subdirectory deployments.

deploymentTarget platform: github-pages or generic.

languagesArray of language codes for generation.

defaultLanguageDefault language code.

generateSitemapGenerate sitemap.xml. Default: false.

generateRobotsTxtGenerate robots.txt. Default: false.

hydrationEnable client-side hydration. Default: false.

generateManifestGenerate manifest.json for PWA. Default: false.

bundleOptimizationSplitting strategy: split or none.

publicDirStatic asset directory to copy into output.

TypeScript

import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)

AppConfig

The primary type for typing your JSON or YAML configuration objects. Import it from sovrium to get full autocomplete and type checking.

PropertyDescription

nameApplication name. Lowercase, npm-compatible (e.g. my-app, @org/app).

version?SemVer version string (e.g. 1.0.0).

description?Single-line application description.

tables?Array of data table definitions with fields, indexes, and constraints.

theme?Design tokens: colors, fonts, spacing, animations, breakpoints, shadows, borderRadius.

pages?Array of page configurations with metadata, sections, and scripts.

auth?Authentication config: strategies, roles, plugins (admin, organization).

languages?Multi-language config: supported languages, default language, translations.

components?Array of reusable component templates with variable substitution.

analytics?Built-in privacy-friendly analytics. Set to true for defaults or pass an object.

TypeScript

import type { AppConfig } from 'sovrium'

const config: AppConfig = {
  name: 'my-app',
  version: '1.0.0',
  description: 'My application',
  tables: [/* ... */],
  theme: {/* ... */},
  pages: [/* ... */],
  auth: {/* ... */},
  languages: {/* ... */},
  components: [/* ... */],
  analytics: true,
}

Incremental complexity

Only name is required. Add tables, theme, pages, auth, languages, components, and analytics as you need them.

Type Reference

Additional TypeScript types exported from the sovrium package. Import them with import type { ... } from "sovrium".

SimpleServer

Returned by start(). A lightweight interface to the running server.

PropertyDescription

urlServer URL including protocol and port (e.g. "http://localhost:3000").

stop()Gracefully stop the server. Returns a Promise that resolves when shutdown is complete.

TypeScript

import { start } from 'sovrium'
import type { SimpleServer } from 'sovrium'

const server: SimpleServer = await start({ name: 'my-app' })
console.log(server.url) // "http://localhost:3000"
await server.stop()     // graceful shutdown

PageConfig

Configuration for a single page. Element of AppConfig['pages'].

TypeScript

const page: PageConfig = {
  name: 'home',
  path: '/',
  sections: [{ type: 'heading', content: 'Welcome' }],
}

TableConfig

Configuration for a single data table. Element of AppConfig['tables'].

TypeScript

const table: TableConfig = {
  id: 1,
  name: 'tasks',
  fields: [{ id: 1, name: 'title', type: 'single-line-text' }],
}

ComponentConfig

Reusable component template with variable placeholders. Element of AppConfig['components'].

TypeScript

const hero: ComponentConfig = {
  name: 'hero',
  type: 'section',
  children: [{ type: 'heading', content: '$title' }],
}

ThemeConfig

Design tokens for colors, typography, spacing, shadows, and more.

TypeScript

const theme: ThemeConfig = {
  colors: { primary: '#3b82f6' },
  fonts: { sans: 'Inter, sans-serif' },
}

AuthConfig

Authentication strategies, roles, and plugin configuration.

TypeScript

const auth: AuthConfig = {
  strategies: [{ type: 'email-password' }],
  roles: ['admin', 'member'],
}

LanguageConfig

Multi-language support with translations and language detection.

TypeScript

const languages: LanguageConfig = {
  supported: ['en', 'fr'],
  default: 'en',
}

AnalyticsConfig

Built-in privacy-friendly analytics. Use true for defaults or an object for custom settings.

TypeScript

// Simple: just enable defaults
const analytics: AnalyticsConfig = true

// Custom settings
const custom: AnalyticsConfig = { retentionDays: 90, excludedPaths: ['/admin'] }

GenerateStaticResult

Returned by build(). Contains the output directory path and the list of generated files.

PropertyDescription

outputDirAbsolute path to the output directory (e.g. "./static").

filesArray of file paths generated during the build (HTML, CSS, assets).

TypeScript

import { build } from 'sovrium'
import type { GenerateStaticResult } from 'sovrium'

const result: GenerateStaticResult = await build({ name: 'my-site', pages: [/* ... */] })
console.log(result.outputDir)     // "./static"
console.log(result.files.length)  // number of generated files

Watch Mode

In development, use Bun's built-in watch mode to automatically restart your script when files change.

Terminal

bun --watch index.ts

Reload vs watch

bun --watch restarts the entire process when any imported file changes. For config-only changes, the CLI's --watch flag is more efficient.

Examples

Common usage patterns with Sovrium in TypeScript.

Minimal server

TypeScript

import { start } from 'sovrium'

const server = await start({
  name: 'my-app',
})

console.log(`Server running at ${server.url}`)

With data tables

TypeScript

import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)

Static site generation

TypeScript

import { build } from 'sovrium'

await build(
  {
    name: 'my-site',
    pages: [
      {
        name: 'home',
        path: '/',
        sections: [
          { type: 'heading', content: 'Welcome' },
          { type: 'paragraph', content: 'Built with Sovrium.' },
        ],
      },
    ],
  },
  {
    outputDir: './dist',
    baseUrl: 'https://example.com',
    deployment: 'github-pages',
    generateSitemap: true,
    generateRobotsTxt: true,
  }
)

Dynamic configuration

TypeScript

import { start } from 'sovrium'
import type { AppConfig, PageConfig, TableConfig, ThemeConfig } from 'sovrium'

// Compose config from typed sub-configs
const theme: ThemeConfig = {
  colors: { primary: process.env.BRAND_COLOR ?? '#3b82f6' },
}

const tables: TableConfig[] = ['users', 'posts'].map((name, i) => ({
  id: i + 1,
  name,
  fields: [
    { id: 1, name: 'title', type: 'single-line-text' as const, required: true },
    { id: 2, name: 'created_at', type: 'datetime' as const },
  ],
}))

const pages: PageConfig[] = [{ name: 'home', path: '/', sections: [] }]

const app: AppConfig = {
  name: 'dynamic-app',
  tables,
  pages,
  theme,
}

await start(app)

CLI Reference Environment Variables

⚡Built with Sovrium