---
title: Configuration et validation
slug: oip-next/v4/configuration-et-validation
icon: {"lucideIcon":"📘"}
createdAt: 2026-08-18T09:30:00.000Z
---

# Vue d'ensemble

La configuration d'un OAV repose sur quatre mécanismes complémentaires :

| Mécanisme               | Fichier             | Rôle                                                                      |
| ----------------------- | ------------------- | ------------------------------------------------------------------------- |
| Déclaration des valeurs | `.env`, `.env.dist` | Porte les valeurs de configuration en développement.                      |
| Validation              | `env-vars.yml`      | Décrit les variables attendues et déclenche la vérification au démarrage. |
| Exposition au client    | `vite.config.js`    | Rend visibles côté navigateur les valeurs qui le nécessitent.             |
| Lecture applicative     | `getEnv`            | Accès unifié aux variables consolidées depuis le code serveur.            |

```mermaid
flowchart LR
    A[Container Startup] --> B[Environment Variable Validation]
    B --> C[Applying Migrations]
    C --> D[Starting the Express Server]
```

# Fichier .env

## Génération

Le fichier `.env` est généré par la commande `oip-tools init` à partir du modèle `.env.dist` présent dans le projet. Les valeurs de `OAV_ID` et `OIP_API_KEY` y sont générées et injectées.

Il est lu par la commande `server:dev`, elle-même appelée par `start-server:dev`.

## Règles d'usage

| Fichier     | Versionné | Contenu                                                                                                  |
| ----------- | --------- | -------------------------------------------------------------------------------------------------------- |
| `.env.dist` | Oui       | Liste des variables attendues, sans valeur sensible. Il documente la configuration nécessaire au projet. |
| `.env`      | Non       | Valeurs locales, dont des secrets. Il ne doit jamais être poussé sur le dépôt.                           |

:::BlockQuote
**\[warn]** Toute nouvelle variable introduite dans le projet doit être ajoutée à `.env.dist` : c'est le seul document qui permette à un autre développeur de reconstituer une configuration complète.
:::

## En production

En production, aucun fichier `.env` n'est utilisé : les variables sont injectées dans le conteneur par l'orchestrateur. Le même artefact Docker est ainsi déployé sur tous les environnements.

# Validation au démarrage

Les variables d'environnement sont vérifiées au démarrage du serveur, à partir du fichier `env-vars.yml` situé à la racine du projet. Cette vérification est réalisée par la bibliothèque `@fasstech/checkenv`.

Elle intervient dans la première phase de la fonction `start` exportée par `@fasstech/oip-starter-utils/server`, avant toute initialisation de l'application Express.

:::BlockQuote
**\[warn]** Une variable obligatoire absente ou invalide interrompt le démarrage. C'est un comportement voulu : un OAV mal configuré s'arrête plutôt que de démarrer dans un état incohérent.
:::

# Lecture des variables côté serveur

La fonction `getEnv`, exportée par `@fasstech/oip-starter-utils/server`, donne accès aux variables consolidées au démarrage. Elle est à préférer à un accès direct à `process.env`.

```javascript
import { getEnv } from '@fasstech/oip-starter-utils/server';

if (getEnv('SECURE_SESSION')) {
  // Secure mode: the client context has been resolved by the sessions service
}

const eventsQueue = `${getEnv('OAV_ID')}.events`;
```

# Exposition des variables au client

Le navigateur n'a pas accès aux variables d'environnement du serveur. Les valeurs nécessaires au client sont injectées à la construction du paquet, via la section `define` du fichier `vite.config.js`.

| Variable d'environnement | Constante exposée   | Nécessité                                 |
| ------------------------ | ------------------- | ----------------------------------------- |
| `CLIENT_ID`              | `__CLIENT_ID__`     | Toujours.                                 |
| `CLIENT_SECRET`          | `__CLIENT_SECRET__` | Toujours.                                 |
| `SERVER_URL`             | `__SERVER_URL__`    | Uniquement pour un projet multi-origines. |

```javascript
import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');

  return {
    // ...
    define: {
      __CLIENT_ID__: JSON.stringify(env.CLIENT_ID),
      __CLIENT_SECRET__: JSON.stringify(env.CLIENT_SECRET),
      __SERVER_URL__: JSON.stringify(env.SERVER_URL)
    }
  };
});
```

:::BlockQuote
**\[warn]** Ces valeurs sont figées dans le paquet client au moment du *build* et sont donc lisibles par n'importe quel utilisateur. N'exposez jamais d'autre secret par ce mécanisme.
:::

# Valeurs typiques par environnement

| Variable         | Développement local                  | Production                                  |
| ---------------- | ------------------------------------ | ------------------------------------------- |
| `NODE_ENV`       | Toute valeur autre que `production`. | `production`                                |
| `SECURE_SESSION` | `false`                              | Ignorée : toujours active.                  |
| `SECURE_COOKIE`  | `false`                              | `true`                                      |
| `SECURE_WS`      | `false`                              | `true`                                      |
| `LOGGER_LEVEL`   | `DEBUG`                              | `ERROR`                                     |
| `SERVER_URL`     | Non renseignée.                      | Renseignée si le projet est multi-origines. |

# Résumé

- En développement, la configuration vit dans `.env`, généré à partir de `.env.dist` ; en production, elle est injectée par l'orchestrateur ;
- `.env.dist` est versionné et fait office de documentation de la configuration, `.env` ne l'est jamais ;
- le fichier `env-vars.yml` décrit les variables attendues et déclenche leur validation au démarrage par `@fasstech/checkenv` ;
- côté serveur, les variables se lisent avec `getEnv` ; côté client, seules `CLIENT_ID`, `CLIENT_SECRET` et `SERVER_URL` sont exposées via `vite.config.js`.
