API TypeScript

Utilisez Sovrium comme bibliothèque dans votre projet TypeScript. Importez start, build et le type AppConfig pour un contrôle programmatique complet avec configuration typée.

TypeScript

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

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

Pourquoi TypeScript ?

Utiliser Sovrium de manière programmatique offre des avantages au-delà de la CLI.

Sécurité des types

Le type AppConfig fournit l'autocomplétion pour chaque propriété et type de champ. Détectez les erreurs à la compilation.

Contrôle programmatique

Générez la configuration dynamiquement, composez des schémas et intégrez Sovrium dans des applications existantes.

Intégration IDE

IntelliSense complet dans VS Code et JetBrains — documentation au survol, aller à la définition et erreurs de type.

start(app, options?)

Démarre un serveur de développement à partir d'un objet de configuration typé. Retourne une instance serveur avec une méthode stop().

TypeScript

import { start } from 'sovrium'

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

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

StartOptions

Deuxième argument optionnel pour configurer le serveur.

PropertyDescription

portNuméro de port (0–65535). 0 sélectionne un port disponible. Par défaut : 3000.

hostnameNom d'hôte du serveur. Par défaut : localhost.

publicDirRépertoire de fichiers statiques. Les fichiers sont servis à leur chemin relatif.

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?)

Génère un site statique à partir d'un objet de configuration typé.

GenerateStaticOptions

Deuxième argument optionnel pour contrôler la sortie statique.

PropertyDescription

outputDirRépertoire de sortie. Par défaut : ./static.

baseUrlURL de base pour le sitemap et les liens canoniques.

basePathPréfixe de chemin pour les déploiements en sous-répertoire.

deploymentPlateforme cible : github-pages ou generic.

languagesTableau de codes de langue pour la génération.

defaultLanguageCode de langue par défaut.

generateSitemapGénérer sitemap.xml. Par défaut : false.

generateRobotsTxtGénérer robots.txt. Par défaut : false.

hydrationActiver l'hydratation côté client. Par défaut : false.

generateManifestGénérer manifest.json pour PWA. Par défaut : false.

bundleOptimizationStratégie de découpage : split ou none.

publicDirRépertoire de ressources statiques à copier.

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

Le type principal pour typer vos objets de configuration JSON ou YAML. Importez-le depuis sovrium pour obtenir autocomplétion et vérification de types.

PropertyDescription

nameNom de l'application. Minuscules, compatible npm (ex : my-app, @org/app).

version?Version SemVer (ex : 1.0.0).

description?Description de l'application sur une seule ligne.

tables?Tableau de définitions de tables avec champs, index et contraintes.

theme?Jetons de design : couleurs, polices, espacement, animations, breakpoints, ombres, borderRadius.

pages?Tableau de configurations de pages avec métadonnées, sections et scripts.

auth?Configuration d'authentification : stratégies, rôles, plugins (admin, organisation).

languages?Configuration multilingue : langues supportées, langue par défaut, traductions.

components?Tableau de composants réutilisables avec substitution de variables.

analytics?Analytiques intégrées respectueuses de la vie privée. Passez true pour les valeurs par défaut ou un objet.

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,
}

Complexité progressive

Seul name est requis. Ajoutez tables, theme, pages, auth, languages, components et analytics selon vos besoins.

Référence des types

Types TypeScript supplémentaires exportés par le package sovrium. Importez-les avec import type { ... } from "sovrium".

SimpleServer

Retourné par start(). Interface légère vers le serveur en cours d'exécution.

PropertyDescription

urlURL du serveur incluant le protocole et le port (ex : "http://localhost:3000").

stop()Arrête le serveur proprement. Retourne une Promise qui se résout quand l'arrêt est terminé.

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 d'une page. Élément de AppConfig['pages'].

TypeScript

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

TableConfig

Configuration d'une table de données. Élément de AppConfig['tables'].

TypeScript

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

ComponentConfig

Modèle de composant réutilisable avec variables. Élément de AppConfig['components'].

TypeScript

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

ThemeConfig

Jetons de design pour les couleurs, la typographie, l'espacement et les ombres.

TypeScript

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

AuthConfig

Stratégies d'authentification, rôles et plugins.

TypeScript

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

LanguageConfig

Support multilingue avec traductions et détection de langue.

TypeScript

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

AnalyticsConfig

Analytics intégrés et respectueux de la vie privée. Utilisez true pour les valeurs par défaut ou un objet pour personnaliser.

TypeScript

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

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

GenerateStaticResult

Retourné par build(). Contient le chemin du répertoire de sortie et la liste des fichiers générés.

PropertyDescription

outputDirChemin absolu vers le répertoire de sortie (ex : "./static").

filesTableau des chemins de fichiers générés durant le 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

Mode surveillance

En développement, utilisez le mode surveillance intégré de Bun pour redémarrer automatiquement votre script.

Terminal

bun --watch index.ts

Rechargement vs surveillance

bun --watch redémarre tout le processus quand un fichier importé change. Pour les changements de configuration uniquement, le --watch de la CLI est plus efficace.

Exemples

Cas d'utilisation courants avec Sovrium en TypeScript.

Serveur minimal

TypeScript

import { start } from 'sovrium'

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

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

Avec des tables de données

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',
  }
)

Génération de site statique

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,
  }
)

Configuration dynamique

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)

Référence CLI Variables d'environnement

⚡Construit avec Sovrium