Skip to main content
View as Markdown

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 une configuration typée.

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

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

Pourquoi TypeScript ?

Utiliser Sovrium par programmation vous offre des avantages au-delà du 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, pas à l'exécution.

Contrôle programmatique

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

Intégration à l'IDE

IntelliSense complet dans VS Code et JetBrains — documentation au survol, accès à 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 de serveur dotée d'une méthode stop().

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.

Propriété Description
port Numéro de port (0–65535). 0 sélectionne un port disponible. Par défaut : 3000.
hostname Nom d'hôte du serveur. Par défaut : localhost.
publicDir Répertoire de fichiers statiques. Les fichiers sont servis à leur chemin relatif. 
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.

Propriété Description
outputDir Répertoire de sortie. Par défaut : ./static.
baseUrl URL de base pour le sitemap et les liens canoniques.
basePath Préfixe de chemin pour les déploiements en sous-répertoire.
deployment Plateforme cible : github-pages ou generic.
languages Tableau de codes de langue pour la génération.
defaultLanguage Code de langue par défaut.
generateSitemap Génère sitemap.xml. Par défaut : false.
generateRobotsTxt Génère robots.txt. Par défaut : false.
hydration Active l'hydratation côté client. Par défaut : false.
generateManifest Génère manifest.json pour les PWA. Par défaut : false.
bundleOptimization Stratégie de découpage : split ou none.
publicDir Répertoire de ressources statiques à copier dans la sortie. 
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,
  }
)

generateAppJsonSchema()

Génère le JSON Schema (Draft-07) de la configuration d'application Sovrium. Retourne un objet simple, adapté à la sérialisation ou à un usage programmatique.

import { generateAppJsonSchema } from 'sovrium'

const schema = generateAppJsonSchema()
Bun.write('app.schema.json', JSON.stringify(schema, null, 2))

validateConfig(config)

Valide une valeur inconnue par rapport à l'AppSchema Sovrium. Retourne un objet résultat indiquant si la configuration est valide, avec la configuration analysée ou le détail des erreurs.

import { validateConfig } from 'sovrium'

const result = validateConfig({ name: 'My App' })
if (result.valid) {
  console.log(result.config.name)
} else {
  console.error(result.errors)
}

AppConfig

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

Propriété Description
name Nom de l'application. En minuscules, compatible npm (par ex. my-app, @org/app).
version? Chaîne de version SemVer (par ex. 1.0.0).
description? Description de l'application en une seule ligne.
tables? Tableau de définitions de tables de données avec champs, index et contraintes.
theme? Jetons de design : couleurs, polices, espacement, animations, points de rupture, ombres, borderRadius.
pages? Tableau de configurations de pages avec métadonnées, sections et scripts.
forms? Définitions de formulaires autonomes qui capturent des soumissions ou déclenchent des automatisations.
auth? Configuration d'authentification : stratégies, rôles, plugins (admin, organization).
languages? Configuration multilingue : langues prises en charge, langue par défaut, traductions.
components? Tableau de modèles de composants réutilisables avec substitution de variables.
automations? Workflows pilotés par événements : déclencheurs plus actions séquentielles.
actions? Modèles d'actions réutilisables référencés depuis les automatisations via $ref.
connections? Identifiants de services externes (OAuth2, clé API, basic, bearer).
agents? Agents IA agissant sous un rôle d'authentification avec des outils restreints.
buckets? Conteneurs de stockage de fichiers nommés avec des limites et des permissions par bucket.
env? Variables d'environnement d'automatisation déclarées, référencées comme $env.NAME.
analytics? Analytique intégrée respectueuse de la vie privée. Définissez true pour les valeurs par défaut ou passez un objet. 
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,
}

Référence des types

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

SimpleServer

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

Propriété Description
url URL du serveur incluant le protocole et le port (par ex. "http://localhost:3000").
stop() Arrête proprement le serveur. Retourne une Promise qui se résout lorsque l'arrêt est terminé. 
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 unique. Élément de AppConfig['pages'].

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

TableConfig

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

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

ComponentConfig

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

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

ThemeConfig

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

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

AuthConfig

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

const auth: AuthConfig = {
  strategies: [{ type: 'emailAndPassword' }],
  roles: [{ name: 'admin' }, { name: 'member' }],
}

LanguageConfig

Prise en charge multilingue avec traductions et détection de langue.

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

AnalyticsConfig

Analytique intégrée respectueuse de la vie privée. Utilisez true pour les valeurs par défaut ou un objet pour des réglages personnalisés.

// 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.

Propriété Description
outputDir Chemin absolu du répertoire de sortie (par ex. "./static").
files Tableau des chemins de fichiers générés pendant le build (HTML, CSS, ressources). 
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

ValidateConfigResult

Retourné par validateConfig(). Indique si la configuration est valide et fournit la configuration analysée ou le détail des erreurs.

Propriété Description
valid Booléen. true si la configuration est valide par rapport à l'AppSchema.
errors Tableau d'objets d'erreurs de validation. Vide lorsque valid est true.
config L'objet AppConfig analysé. Présent uniquement lorsque valid est true. 
import { validateConfig } from 'sovrium'
import type { ValidateConfigResult } from 'sovrium'

const result: ValidateConfigResult = validateConfig({ name: 'my-app' })
console.log(result.valid) // true or false
console.log(result.errors) // validation error array (empty if valid)
console.log(result.config) // parsed AppConfig (if valid)

Mode surveillance

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

bun --watch index.ts

Exemples

Cas d'utilisation courants avec Sovrium en TypeScript.

Serveur minimal

import { start } from 'sovrium'

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

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

Avec des tables de données

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

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

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: 'date' as const, includeTime: true },
  ],
}))

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

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

await start(app)