> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/fr/development/dev-environment.md).

# Environnement de développement

MyIP est un seul dépôt avec deux moitiés : une **Vue 3** application monopage sous `frontend/` et une **Express 5** API sous `api/` + `backend-server.js`. Une seule commande exécute les deux.

## Prérequis

<table><thead><tr><th width="180">Outil</th><th width="220">Version</th><th>Remarques</th></tr></thead><tbody><tr><td><strong>Node.js</strong></td><td>24</td><td>Ce que l'image Docker (<code>node:24-alpine</code>) et la CI utilisent toutes deux.</td></tr><tr><td><strong>pnpm</strong></td><td>Verrouillé dans <code>package.json</code></td><td>N'installez pas manuellement une autre version — voir ci-dessous.</td></tr><tr><td><strong>Git</strong></td><td>Toute version récente</td><td>Les contributions partent de <code>dev</code>.</td></tr></tbody></table>

Le moyen le plus simple d'obtenir la bonne version de pnpm est Corepack, qui est fourni avec Node :

```bash
corepack enable
```

Corepack lit le `packageManager` champ dans `package.json` et provisionne exactement cette version de pnpm. Le Dockerfile et le workflow CI font de même, afin que votre chaîne d'outils locale corresponde à la leur.

## pnpm uniquement

{% hint style="danger" %}
**N'exécutez jamais `npm install` ou `yarn` dans ce dépôt.**
{% endhint %}

Trois choses dépendent spécifiquement de pnpm :

* **`packageManager` dans `package.json` verrouille la version exacte de pnpm.** Corepack, le Dockerfile et le workflow GitHub Actions le lisent tous, de sorte que tout le monde résout le même arbre de dépendances.
* **`pnpm-lock.yaml` est commité.** npm écrirait `package-lock.json` et yarn écrirait `yarn.lock` — un second fichier de verrouillage concurrent que rien dans le projet ne lit. La CI installe avec `--frozen-lockfile`, donc un fichier de verrouillage pnpm désynchronisé fait échouer la compilation immédiatement.
* **`pnpm-workspace.yaml` contient les approbations des scripts d'installation** (`allowBuilds`) pour les quelques paquets autorisés à exécuter des scripts postinstall. npm et yarn ignorent complètement ce fichier.

## Installer et exécuter

{% stepper %}
{% step %}

#### Cloner et installer

```bash
git clone https://github.com/jason5ng32/MyIP.git
cd MyIP
pnpm install
```

{% endstep %}

{% step %}

#### Créez votre `.env`

```bash
cp .env.example .env
```

Tout dans `.env.example` est facultatif pour *démarrer* l'application, mais la géolocalisation IP reste cassée sans identifiants MaxMind. Voir [Configuration de MaxMind](/developer/fr/getting-started/maxmind-setup.md) et [Variables d'environnement](/developer/fr/reference/environment-variables.md).
{% endstep %}

{% step %}

#### Démarrer les deux moitiés

```bash
pnpm dev
```

Cela lance le serveur de développement Vite et le backend (sous `nodemon`) côte à côte via `concurrently`. Modifiez un `.vue` fichier et Vite le rechargera à chaud ; modifiez tout ce que le backend importe et nodemon redémarre l'API.
{% endstep %}

{% step %}

#### Ouvrez l’application

Accédez à `http://localhost:18966`. Le serveur de développement Vite fait suivre `/api` vers le backend pour vous.
{% endstep %}
{% endstepper %}

## Ports

Les deux ports proviennent de `.env` et les valeurs par défaut sont les suivantes :

| Variable        | Par défaut | Utilisé par                                                                      |
| --------------- | ---------- | -------------------------------------------------------------------------------- |
| `FRONTEND_PORT` | `18966`    | Serveur de développement Vite (`pnpm dev`) et le serveur statique (`pnpm start`) |
| `BACKEND_PORT`  | `11966`    | API Express (`backend-server.js`)                                                |

Le serveur de développement Vite écoute sur `0.0.0.0`, afin que vous puissiez y accéder depuis un autre appareil sur votre réseau local, et fait suivre `/api` → `http://localhost:<BACKEND_PORT>`. Vous avez rarement besoin d'accéder directement au port du backend.

{% hint style="warning" %}
**Les requêtes vers `/api/*` ont besoin d'un `Referer`.** Un middleware global (`requireReferer` dans `common/guards.js`) rejette les requêtes dont le référent ne figure pas sur la liste d'autorisation. `localhost` est autorisé, donc le navigateur va bien — mais un simple `curl http://localhost:11966/api/...` obtient un `403`. `-H 'Referer: http://localhost/'` lors des tests manuels.
{% endhint %}

## Local `.env` notes

* `.env` est chargé par **les deux** les deux moitiés : `backend-server.js` à l'exécution et `vite.config.js` à la compilation.
* Les variables préfixées `VITE_` sont **intégrées au bundle du frontend à la compilation**. En changer une nécessite un `pnpm dev` redémarrage, pas seulement un rafraîchissement de page — et ne placez jamais un secret derrière un nom `VITE_` .
* Les intégrations facultatives restent totalement désactivées lorsque leur variable est vide. Pas de DSN Sentry signifie qu'aucun code Sentry ne se charge du tout ; pas de configuration Firebase signifie que le SDK n'est jamais récupéré. Vous pouvez développer la majeure partie de l'application avec un `.env`.
* Les réglages de journalisation sont `LOG_LEVEL`, `LOG_FORMAT`, et `LOG_HTTP` — voir [Journalisation](/developer/fr/configuration/logging.md). Il n'y a pas de `NODE_ENV` des interrupteurs partout dans ce projet.

## Chaque script

| Commande              | Ce qu'elle fait                                                              |
| --------------------- | ---------------------------------------------------------------------------- |
| `pnpm dev`            | Serveur de développement Vite + backend sous nodemon, ensemble               |
| `pnpm build`          | Compilation du frontend de production dans `dist/`                           |
| `pnpm preview`        | Serveur de prévisualisation de Vite pour la sortie compilée                  |
| `pnpm test`           | `node --test tests/*.test.js`                                                |
| `pnpm check`          | `test` + `build` — le contrôle automatique avant commit                      |
| `pnpm start`          | Serveur statique du frontend + backend (ce qu'exécute un hôte de production) |
| `pnpm start-backend`  | Backend uniquement                                                           |
| `pnpm start-frontend` | Serveur statique du frontend uniquement                                      |

## Le contrôle automatique

Avant de transmettre un changement — une PR, un commit, une demande de revue — exécutez :

```bash
pnpm check
```

Autrement dit `pnpm test` suivi de `pnpm build`. C'est la même paire d'étapes que la CI exécute à chaque push et chaque pull request sur `main` et `dev`, donc un résultat local au vert `vert` signifie généralement un passage CI vert.

{% hint style="info" %}
**Les changements visuels ne peuvent pas s'auto-tester.** Le lanceur de tests Node ne rend pas les composants Vue et ne pilote pas de navigateur. Si votre changement est visuel, indiquez-le explicitement dans la PR et faites-le examiner par une personne dans `pnpm dev`. Voir [Tests](/developer/fr/development/testing.md).
{% endhint %}

## Extras pratiques en développement

* **Console mobile.** Sur un téléphone ou une tablette, `pnpm dev` charge automatiquement vConsole — un panneau d'outils de développement à l'écran. C'est réservé au développement et au mobile ; cela n'est jamais inclus dans une compilation.
* **Cliquer pour source.** Le `code-inspector-plugin` est intégré au serveur de développement, ce qui vous permet d'aller d'un élément dans le navigateur à sa ligne source dans votre éditeur.
* **Hôtes de développement supplémentaires.** `vite.config.js` autorise `dev.ipcheck.ing` et `test.ipcheck.ing` en plus de localhost, pour tester avec un vrai nom d'hôte.

## Ensuite

* [Conventions de codage](/developer/fr/development/coding-conventions.md) — les règles que votre changement est censé suivre.
* [Ajout d'un nouvel outil](/developer/fr/development/adding-a-new-tool.md) — le parcours de bout en bout.
* [Structure du projet](/developer/fr/architecture/project-structure.md) — ce qui se trouve où.
* [Comment contribuer](/developer/fr/contributing/how-to-contribute.md) — discipline des branches et consignes pour les PR.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/fr/development/dev-environment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.