---
title: Initialisation du projet
slug: oip-next/v4/initialisation-projet
icon: {"lucideIcon":"📘"}
createdAt: 2026-08-18T09:00:00.000Z
---

# Vue d'ensemble

Un projet OAV se crée à partir du modèle de projet **OIP Starter**.

Cette page décrit les trois opérations à enchaîner :

1. récupérer le modèle de projet et l'attacher à votre propre dépôt ;
2. installer les dépendances ;
3. initialiser le projet avec `oip-tools init`.

:::BlockQuote
**\[info]** Assurez-vous d'avoir réuni l'ensemble des [pré-requis](https://doc.fasst.tech/oip-next/v4/pre-requis) avant de commencer.
:::

# Récupération du modèle de projet

Clonez la branche `v4` du modèle de projet, détachez l'historique Git d'origine, puis rattachez le projet à votre propre dépôt :

```shell
git clone --branch v4 --single-branch --depth 1 git@github.com:fasst/fasst-oip-starter.git <project-name>
cd <project-name>
rm -rf ./.git
git init
git add .
git commit -m "init project from oip-starter"
git remote add origin https://github.com/<owner>/<repository>.git
git push -u origin main
```

| Paramètre        | Description                                         |
| ---------------- | --------------------------------------------------- |
| `<project-name>` | Nom du répertoire local du projet.                  |
| `<owner>`        | Organisation ou compte GitHub hébergeant le projet. |
| `<repository>`   | Nom du dépôt distant du projet.                     |

:::BlockQuote
**\[warn]** La suppression du répertoire `.git` est volontaire : elle évite de conserver l'historique du modèle de projet et de pousser accidentellement des commits vers `fasst/fasst-oip-starter`.
:::

# Installation des dépendances

```shell
npm install
```

Cette commande installe le socle applicatif (`@fasstech/oip-starter-utils`), la bibliothèque d'accès aux données (`@fasstech/oip-core`), l'outillage (`@fasstech/oip-tools`) et leurs dépendances.

:::BlockQuote
**\[warn]** Un échec d'authentification à cette étape signale un accès manquant au registre npm privé `@fasstech`. Vérifiez votre fichier `.npmrc` avant de poursuivre.
:::

# Initialisation par OIP Tools

```shell
npx oip-tools init --oav-name <oav-name> --first-view-name <first-view-name>
```

## Options

| Option              | Obligatoire | Description                                                                                               |
| ------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `--oav-name`        | Oui         | Nom de l'OAV. Il est notamment injecté dans la balise `<title>` du fichier `index.html`.                  |
| `--first-view-name` | Non         | Nom de la première vue du parcours. Le format attendu est `^[a-z0-9]+(_[a-z0-9]+)*$`, par exemple `home`. |

## Effets de la commande

La commande `init` met en place l'ensemble minimal des fichiers nécessaires au démarrage :

| Élément                          | Emplacement        | Contenu                                                                                                      |
| -------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
| Configuration des entités        | `config/entities/` | Modèle de données minimal : une entité racine `Project` portant une propriété `externalId` de type `string`. |
| Code des entités                 | `entities/`        | Fonctions de manipulation générées à partir de la configuration.                                             |
| Migration initiale               | `migrations/`      | Migration créant le schéma du modèle en base de données.                                                     |
| Configuration de la première vue | `config/views/`    | Fichier YAML de la vue, si `--first-view-name` est fournie.                                                  |
| Code de la première vue          | `views/`           | Fichiers client et serveur de la vue, si `--first-view-name` est fournie.                                    |
| Transition de la première vue    | `transitions/`     | Fichier de transition associé, si `--first-view-name` est fournie.                                           |
| Fichier d'environnement          | `.env`             | Généré à partir de `.env.dist` ; les valeurs de `OAV_ID` et `OIP_API_KEY` sont générées et injectées.        |
| Page hôte                        | `index.html`       | Nom de l'OAV injecté dans la balise `<title>`.                                                               |

Arborescence produite :

```none
Project Root/
├── config/
│   ├── entities/
│   │   └── entities.config.mjs
│   └── views/
│       └── 0000-MY-FIRST-VIEW.yml
├── entities/
│   ├── Project/
│   │   └── index.mjs
│   └── entities.mjs
├── migrations/
│   └── 0000000000000_migration.js
├── transitions/
│   └── MY_FIRST_VIEW.mjs
├── views/
│   └── my-first-view/
│       ├── client/
│       │   └── ...
│       └── server/
│           └── ...
├── .env
└── index.html
```

:::BlockQuote
**\[info]** La commande doit être exécutée depuis la racine du projet. Si un fichier `.env` existe déjà, vérifiez son contenu avant de relancer l'initialisation.
:::

# Vérification de l'initialisation

Après exécution de la commande, contrôlez les points suivants :

- le fichier de configuration des entités existe dans `config/entities/` ;
- le répertoire `entities/Project/` contient un fichier `index.mjs` ;
- le répertoire `migrations/` contient une migration initiale ;
- le fichier `.env` existe et porte des valeurs pour `OAV_ID` et `OIP_API_KEY` ;
- si l'option `--first-view-name` a été utilisée, la vue, sa configuration et sa transition sont présentes.

# Ce qu'il reste à faire

:::BlockQuote
**\[warn]** Un projet fraîchement initialisé ne démarre pas en l'état. Trois fonctions de décrochage doivent d'abord être implémentées dans `server/index.mjs` : `resolveProjectFromContext`, `resolveFirstView` et `validateProjectId`. Un exemple d'implémentation de chacune est fourni dans le fichier.
:::

| Fonction                    | Rôle                                                                                |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `resolveProjectFromContext` | Résout l'identifiant de l'entité `Project` à partir du contexte client.             |
| `validateProjectId`         | Vérifie qu'un `projectId` passé en paramètre d'URL correspond à un projet existant. |
| `resolveFirstView`          | Détermine la première vue du parcours.                                              |

Ces implémentations, ainsi que le démarrage des services et des deux applications, sont décrites dans la section « [Lancement du projet](https://doc.fasst.tech/oip-next/v4/lancement-projet) ».

# Résumé

- Un projet OAV démarre par un clone de la branche `v4` du modèle OIP Starter ;
- `npm install` installe le socle, la bibliothèque d'accès aux données et l'outillage ;
- `oip-tools init` produit le modèle de données minimal, la migration initiale, le fichier `.env` et, optionnellement, une première vue complète ;
- le projet n'est pas encore exécutable : les trois fonctions de décrochage restent à implémenter.
