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

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

:::callout
**Zéro runtime, sous licence MIT.** `@sovrium/types` ne livre que des fichiers `.d.ts`, générés depuis le même `AppSchema` que celui décodé par le serveur. Rien n'en atteint votre bundle, et ce n'est pas le moteur — pour `import { start } from 'sovrium'`, voir l'[API TypeScript](/fr/docs/typescript).
:::

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

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

```typescript
// 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](/fr/docs/configuration-files) — les deux autres formats.
- [Configurations multi-fichiers](/fr/docs/configuration-refs) — l'équivalent YAML/JSON des imports.
- [Schéma JSON](/fr/docs/json-schema) — les mêmes garanties pour les auteurs YAML.
- [API TypeScript](/fr/docs/typescript) — exécuter Sovrium comme bibliothèque.