Initialisation du projet

12 min

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 :

récupérer le modèle de projet et l'attacher à votre propre dépôt ;

installer les dépendances ;

initialiser le projet avec oip-tools init.

[info] Assurez-vous d'avoir réuni l'ensemble des pré-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 :

git clone --branch v4 --single-branch --depth 1 [email protected]: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.

[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

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.

[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

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 :

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

[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

[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 ».

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.