Configurations TypeScript

Une configuration peut être un module TypeScript plutôt qu'un fichier YAML ou JSON. Le CLI accepte app.ts partout où il accepte app.yaml — la différence se joue entièrement dans votre éditeur, où chaque propriété, type de champ et type de composant est vérifié au fil de la frappe.

@sovrium/types

Les types viennent d'un paquet séparé : rédiger une configuration n'amène donc jamais le moteur dans votre projet.

bun add -d @sovrium/types

// app.ts
import { defineConfig } from '@sovrium/types'

export default defineConfig({
  name: 'my-app',
  version: '1.0.0',
  description: 'A simple todo list',
  tables: [
    {
      id: 1,
      name: 'tasks',
      fields: [
        { id: 1, name: 'title', type: 'single-line-text', required: true },
        { id: 2, name: 'done', type: 'checkbox', default: false },
      ],
    },
  ],
})

sovrium start app.ts
sovrium validate app.ts

defineConfig est une fonction identité : elle retourne son argument intact et l'annote comme AppConfig. C'est tout ce qu'elle a à faire — cette annotation suffit à transformer un type de champ invalide, un type de composant inconnu ou une propriété obligatoire manquante en erreur à la frappe plutôt qu'au démarrage.

Composer avec des imports

$ref est un mécanisme YAML/JSON ; TypeScript en possède déjà un. Scindez les sections en modules et assemblez-les dans defineConfig :

// config/tables.ts
import type { TableConfig } from '@sovrium/types'

export const companies: TableConfig = {
  id: 1,
  name: 'Companies',
  fields: [
    { id: 1, name: 'name', type: 'single-line-text', required: true },
    { id: 2, name: 'website', type: 'url' },
  ],
}

// app.ts
import { defineConfig } from '@sovrium/types'
import { companies } from './config/tables'

export default defineConfig({
  name: 'crm-workspace',
  tables: [companies],
})

Parce qu'il s'agit d'un vrai module, la configuration peut aussi être calculée — lire une valeur dans l'environnement, générer une table par entité, dériver des routes depuis une liste.

Quand préférer TypeScript

Choisissez TypeScript quand	Choisissez le YAML quand
La configuration est assez grosse pour que les fautes coûtent du débogage	Elle est petite et bien plus lue que modifiée
Des sections se répètent et vous préféreriez générer que copier	Des non-développeurs doivent la lire ou l'amender
Des valeurs viennent de l'environnement ou d'une autre source	Vous voulez qu'elle reste manifestement de la donnée, pas du code
Vous voulez les erreurs dans l'éditeur plutôt qu'à sovrium validate	Vous la voulez relisible en diff sans étape de build

Les deux décrivent le même objet : ce n'est donc pas une porte à sens unique. Une configuration YAML se transcrit à la main en TypeScript, et réciproquement.

Pages associées

• Fichiers de configuration : YAML et JSON — les deux autres formats.
• Configurations multi-fichiers — l'équivalent YAML/JSON des imports.
• Schéma JSON — les mêmes garanties pour les auteurs YAML.
• API TypeScript — exécuter Sovrium comme bibliothèque.