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

```yaml
# 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 }
```

```json
{
  "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 :

```bash
sovrium start app.yaml
sovrium start app.json
```

:::callout
**La détection du format se fait par extension.** Sovrium achemine les fichiers `.yaml`/`.yml` vers son analyseur YAML et les fichiers `.json` vers son analyseur JSON. La forme de l'objet résultant est identique — chaque exemple de cette documentation peut être transcrit d'un format à l'autre.
:::

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

```bash
bun add -d @sovrium/types
```

```typescript
// 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 },
      ],
    },
  ],
})
```

```bash
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`.

:::callout
**`@sovrium/types` vs le paquet `sovrium`.** `@sovrium/types` ne fournit que des types (sous licence MIT, sans aucun runtime). Utilisez-le pour rédiger des fichiers de configuration. Pour exécuter Sovrium par programmation (`import { start } from 'sovrium'`), voir l'[API TypeScript](/fr/docs/typescript).
:::

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

```yaml
# 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
```

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

:::callout
**Les configurations TypeScript se composent différemment.** `$ref` est un mécanisme YAML/JSON. En TypeScript, vous composez avec des `import` ordinaires — définissez des sous-configurations dans des modules séparés et assemblez-les à l'intérieur de `defineConfig({ ... })`.
:::

## 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](/fr/docs/cli#configuration-sources) 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.

```bash
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

- [Concepts fondamentaux](/fr/docs/concepts) — l'anatomie de l'objet de configuration.
- [Référence CLI](/fr/docs/cli) — chaque commande, option et source de configuration.
- [API TypeScript](/fr/docs/typescript) — exécuter Sovrium comme bibliothèque.
- [Vue d'ensemble du schéma](/fr/docs/overview) — la référence complète des propriétés racine.