Skip to main content
View as Markdown

Fichiers de configuration

Sovrium charge votre application à partir d'un fichier de configuration. Le même objet de configuration peut être écrit en YAML, JSON ou TypeScript, réparti sur plusieurs fichiers avec $ref, et vérifié à l'avance avec sovrium validate.

YAML et JSON

La configuration la plus simple est un fichier YAML ou JSON. Le YAML est recommandé pour une rédaction manuelle — il prend en charge les commentaires, nécessite moins de ponctuation et est plus facile à lire. Le JSON est pratique lorsqu'on génère des configurations par programmation.

# app.yaml
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 }
{
  "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 }
      ]
    }
  ]
}

Exécutez l'un ou l'autre avec le CLI :

sovrium start app.yaml
sovrium start app.json

TypeScript avec defineConfig

Pour un typage complet et l'autocomplétion dans l'IDE, rédigez votre configuration en TypeScript et validez-la par rapport au paquet @sovrium/types. @sovrium/types est un paquet sans dépendance de types TypeScript extraits directement du schéma Sovrium.

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 un assistant d'identité : il retourne son argument inchangé mais l'annote avec le type AppConfig, de sorte que votre éditeur signale les types de champs invalides, les types de composants inconnus et les propriétés obligatoires manquantes au fur et à mesure que vous tapez — sans import de type séparé ni satisfies.

Configurations multi-fichiers avec $ref

À mesure qu'une application grandit, un fichier unique devient difficile à gérer. Sovrium prend en charge $ref pour répartir la configuration sur plusieurs fichiers. Tout objet contenant exactement une clé, $ref, dont la valeur est un chemin relatif, est remplacé par le contenu analysé de ce fichier avant la validation.

# app.yaml
name: crm-workspace
version: 2.0.0

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

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

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

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

agents:
  - $ref: ./config/agents/records-assistant.yaml
# config/tables/companies.yaml
id: 1
name: Companies
fields:
  - { id: 1, name: name, type: single-line-text, required: true }
  - { id: 2, name: website, type: url }
Règle Comportement
Résolution de chemin Les chemins $ref se résolvent relativement au fichier qui les contient, et non au répertoire de travail.
Formats mixtes Un fichier racine YAML peut faire $ref vers une partie JSON et vice versa — chaque fichier est analysé selon son extension.
Éléments de tableau Un $ref peut remplacer un élément entier de tableau (- $ref: ...) ou une valeur d'objet entière.
Moment de résolution Tous les $ref sont résolus en un seul objet avant la validation du schéma, de sorte que les vérifications inter-sections voient l'application complète.

Chargement sans fichier

La configuration peut également provenir de la variable d'environnement APP_SCHEMA au lieu d'un chemin de fichier — JSON en ligne, YAML en ligne ou URL distante. Voir la Référence CLI pour plus de détails.

Valider une configuration

sovrium validate vérifie un fichier de configuration par rapport au schéma d'application complet — y compris les règles inter-sections telles que « une automatisation d'enregistrement doit référencer une table existante » — et retourne un code de sortie non nul avec le détail des erreurs en cas de problème.

sovrium validate app.yaml
sovrium validate app.ts
sovrium validate config.json

Exécutez-la en CI pour détecter les erreurs de configuration avant le déploiement. Comme la validation exécute le même schéma que celui utilisé par le serveur au démarrage, une configuration qui passe validate est garantie de démarrer.

Étapes suivantes