Le package.json et le monorepo

Précédemment. Le projet est installé, vérifié par pnpm check, et nous savons travailler avec. Avant d'entrer dans le code, regardons les fichiers qui disent à chaque outil comment le lire.

Cette partie passe en revue les fichiers de configuration du dépôt : ce qu'ils règlent, qui les lit, et ce qui casse quand on y touche. Elle commence par le plus central, le package.json, et par ce qu'il devient dans un monorepo : plusieurs paquets dans un seul dépôt Git.

Un dépôt, quatre paquets#

pnpm sait qu'il gère plusieurs paquets parce qu'un fichier, à la racine, le lui dit :

packages:  - apps/*  - packages/*

Chaque dossier de apps/ et de packages/ qui contient un package.json est un paquet du workspace. pnpm install, lancé une fois à la racine, installe les dépendances de tous les paquets d'un coup, dans un seul node_modules partagé.

Le nom d'un paquet est celui de son package.json, pas celui de son dossier. C'est lui qu'utilise l'option --filter : pnpm --filter web build lance le script build du paquet nommé web. Un nom à portée (@workspace/backend) peut être désigné sans sa portée tant qu'il n'y a pas d'ambiguïté : pnpm --filter backend typecheck, que lance pnpm check, vise @workspace/backend.

Le package.json d'un paquet#

Le plus court du dépôt montre tout ce qu'un paquet déclare :

{  "name": "@workspace/finder-core",  "version": "0.0.0",  "private": true,  "type": "module",  "exports": {    ".": "./src/index.ts",    "./cart": "./src/cart/usePickerCartStore.ts"  },  "scripts": {    "typecheck": "tsc --noEmit"  },  "dependencies": {    "@workspace/contracts": "workspace:*"  }}

"workspace:*" est propre aux workspaces pnpm : la dépendance n'est pas téléchargée du registre, c'est le dossier packages/contracts lui-même, relié par un lien symbolique dans node_modules/@workspace/contracts. Une modification de contracts est donc visible immédiatement par les paquets qui en dépendent, sans publication ni réinstallation.

Les paquets ne sont pas compilés séparément : il n'y a pas de dossier dist/. Leurs fichiers TypeScript sont lus tels quels par Next.js et par tsc, comme s'ils faisaient partie de l'application. C'est ce qui permet de modifier le backend et de voir le changement au rechargement suivant.

Deux façons de se joindre#

Le code du projet n'importe pourtant jamais @workspace/backend ou @workspace/contracts par leur nom de paquet. Il passe par des alias TypeScript :

"@contracts/*": ["../../packages/contracts/src/*"],"@backend/*": ["../../packages/backend/src/*"],

import { prisma } from "@backend/prisma" est réécrit, à la compilation, en packages/backend/src/prisma. L'alias ne dépend ni du lien symbolique ni du champ exports : il pointe directement dans le code source.

Le projet a donc deux mécanismes pour la même chose : les dépendances workspace:*, déclarées mais peu utilisées par les imports, et les alias, qui font réellement le travail. C'est un héritage de son histoire plus qu'un choix : un paquet pourrait se contenter des dépendances de workspace et de ses exports. Le chapitre suivant, sur TypeScript, détaille les alias et leur contrainte principale : tout tsconfig qui compile un fichier doit connaître les alias que ce fichier utilise.

Les dépendances : où elles sont déclarées#

La règle habituelle d'un monorepo veut que chaque paquet déclare ce qu'il importe. Le projet s'en écarte : le package.json de la racine porte l'essentiel des dépendances (environ quatre-vingts, de React à Prisma), et celui de apps/web seulement celles ajoutées plus tard (le stockage S3, MDX, l'aperçu des PDF…).

Cela fonctionne grâce à la résolution de Node : un import "zod" depuis apps/web/src/… cherche node_modules/zod dans le dossier du fichier, puis dans chaque dossier parent, jusqu'à la racine du dépôt, où pnpm l'a installé. L'inconvénient : rien n'empêche un paquet d'importer une bibliothèque qu'il ne déclare pas, et le jour où un paquet serait sorti du dépôt, ses vraies dépendances seraient à reconstituer.

dependencies et devDependencies#

dependencies liste ce dont le code a besoin pour tourner, devDependencies ce qui ne sert qu'à le développer (types, linters, outils de build). Pour une application privée comme celle-ci, la différence est surtout documentaire : l'image de production installe tout, puis Next.js ne garde dans son build que ce que le code utilise réellement.

RUN --mount=type=cache,id=pnpm,target=/pnpm/store \  pnpm config set store-dir /pnpm/store \  && pnpm install --frozen-lockfile

Les versions et le fichier de verrouillage#

Dans un package.json, "zod": "^4.1.12" est une plage : toute version 4 à partir de 4.1.12. La version réellement installée est écrite, avec son empreinte, dans pnpm-lock.yaml, pour chaque paquet de l'arbre de dépendances. Ce fichier est versionné : tous les développeurs et le serveur installent exactement les mêmes versions.

pnpm install met le fichier de verrouillage à jour si un package.json a changé. pnpm install --frozen-lockfile, utilisé par le Dockerfile, refuse au contraire de le modifier et échoue si le fichier ne correspond plus aux package.json : la production n'installe jamais une version qui n'a pas été vue en développement.

Forcer une version : overrides#

Deux bibliothèques peuvent demander deux versions différentes d'une même dépendance. Pour l'éditeur de texte, deux copies de @tiptap/pm dans l'arbre cassaient l'éditeur : chacune croyait être la seule. Le champ pnpm.overrides impose une version unique à tout l'arbre :

"pnpm": {  "overrides": {    "@tiptap/pm": "3.27.3",    "@tiptap/core": "3.27.3"  }},

Les scripts d'installation des dépendances#

Certaines bibliothèques lancent un script à leur installation (compiler un binaire natif, télécharger un fichier). Depuis la version 10, pnpm ne les exécute plus par défaut : c'est une protection contre un paquet malveillant. Chaque exception se déclare dans pnpm-workspace.yaml ; le projet y range sharp parmi les scripts ignorés, ses binaires précompilés arrivant par des paquets séparés :

ignoredBuiltDependencies:  - sharp

Les scripts#

Le champ scripts donne un nom court aux commandes du projet. pnpm dev lance le script dev du package.json le plus proche ; s'il n'existe pas, pnpm cherche une commande installée du même nom.

Les scripts de la racine délèguent souvent au paquet concerné, qui a les siens :

"scripts": {  "dev": "next dev",  "build": "next build --webpack",  "start": "next start",  "lint": "eslint . --max-warnings 0",  "typecheck": "tsc --noEmit"},

postinstall est un nom réservé : pnpm l'exécute de lui-même après pnpm install, comme preinstall avant. Les autres noms ne s'exécutent que lorsqu'on les appelle.

Récapitulatif#

À suivre#

Les paquets se rejoignent par des alias, et chaque paquet a son tsconfig. Qui compile quoi, avec quelles options, et pourquoi le même alias doit-il être déclaré dans plusieurs fichiers ?