Ajouter un projet
Comment Joppa analyse un dossier, nomme le projet, trouve ses serveurs de dev et leur propose des domaines.
Trois façons d’ajouter
- Glisser-déposer : déposez un dossier n’importe où dans la fenêtre (« Déposez pour ajouter le projet »).
- Bouton ou raccourci : + nouveau à côté de Projets dans la barre latérale, Ajouter un projet sur l’accueil, ou N n’importe où.
- Terminal : dans le TUI, touche a sur la section Projets, ou l’outil MCP
add_project.
La fenêtre Ajouter un projet montre ce que Joppa a trouvé ; rien n’est enregistré avant que vous validiez (⌘ ⏎).
Le nom et l’icône
Le nom vient du champ name de package.json (sans le scope @org/), sinon du nom du dossier. Il est converti en minuscules sans accents ni espaces : Kiné Santé devient kine-sante.
L’icône est générée à partir du nom. Changez-la à tout moment avec I sur la page du projet : motifs générés, initiales, pictogrammes, ou votre propre image (.svg, .png, .jpg, .webp, 180 Ko au plus), tramée aux couleurs de Joppa.
Ce que Joppa détecte
| Stack | Indice | Port par défaut |
|---|---|---|
Vite, Vite+ (vp), React Router, Remix, SvelteKit |
script dev |
5173, ou port: dans vite.config |
| Astro | script dev |
4321, ou port: dans astro.config |
| Next.js | script dev |
3000 |
| Nuxt | script dev |
3000 |
| Angular, Nx (Angular, webpack) | ng serve, cible Nx |
4200 |
| Create React App, Docusaurus | react-scripts start, docusaurus start |
3000 |
| Vue CLI, Gatsby, Storybook, Expo | leur commande | 8080, 8000, 6006, 8081 |
| Node (autre serveur) | port écrit dans le script ou dans le code | celui trouvé |
| Laravel | fichier artisan |
8000 (php artisan serve) |
| Symfony, autre PHP | public/index.php et composer.json |
8000 (php -S) |
| Bun | bun.lock / bun.lockb |
— |
| Docker Compose | compose.yaml, docker-compose.yml… |
ports publiés |
Joppa lit le script dev de la racine et de chaque package d’un monorepo : workspaces npm, yarn ou bun, pnpm-workspace.yaml, lerna.json, projets Nx. Un port est reconnu sous ces formes : --port 3000, -p 3000, --port=3000, PORT=3000, ${PORT:-3000}. Le détail est dans Processus.
Pour Laravel, le domaine de base va à php artisan serve ; le serveur Vite, qui ne sert que les assets, n’en reçoit pas.
Les sous-domaines proposés
Avec un seul serveur, le projet reçoit le domaine de base : monprojet.test. Dans un monorepo, chaque app reçoit un sous-domaine d’après le nom de son dossier :
| Dossier de l’app | Domaine |
|---|---|
web, app, frontend, client, dashboard |
app.monprojet.test |
marketing, site, www, website, landing, home |
monprojet.test |
api, server, backend |
api.monprojet.test |
autre (docs, admin…) |
docs.monprojet.test |
Deux apps qui tomberaient sur le même nom sont numérotées : app, app2.
Les interfaces web de Docker Compose
Les services Compose qui publient une interface web connue reçoivent aussi leur domaine :
| Service | Port | Domaine |
|---|---|---|
| Mailpit, MailHog | 8025 | mail.monprojet.test |
| MinIO (console) | 9001 | minio.monprojet.test |
| RabbitMQ (management) | 15672 | rabbitmq.monprojet.test |
| Adminer | 8080 | adminer.monprojet.test |
| phpMyAdmin | 80 | phpmyadmin.monprojet.test |
| pgAdmin | 80 | pgadmin.monprojet.test |
Les autres ports publiés (bases de données, caches) sont listés comme « Non routés (pas des interfaces web) ». Si le Compose contient PostgreSQL, MySQL, MariaDB, Redis ou Valkey, la fenêtre propose aussi d’importer leurs données dans Joppa : voir Import depuis Docker Compose.
Un dépôt avec joppa.toml
Quand le dossier contient un joppa.toml (la configuration qu’une équipe partage), la fenêtre part de lui :
- le nom est celui de sa section
[project]; - les domaines sont ses
[[domain]], la source affichée étant « joppa.toml » ; - sous Configuration d’équipe · joppa.toml, le plan liste le reste, une étape par ligne : créer le serveur ou réutiliser celui de la machine, créer la base avec ses extensions, lier le projet, écrire le
.env(Voir le diff), épingler Node, le gestionnaire de paquets et PHP, régler les worktrees. Les étapes déjà en place sont repliées sous « déjà en place ».
Décochez ce que vous ne voulez pas : les étapes qui en dépendent se décochent avec elle. Une étape impossible ici est grisée avec la raison : un moteur réservé à Joppa Pro, un domaine déjà pris par un autre projet. Les écarts sont signalés sans rien bloquer : un serveur PostgreSQL de la machine dans une autre version que celle demandée est réutilisé, et un .node-version du dépôt l’emporte sur la section [runtime].
Ajouter et préparer (⌘ ⏎) ajoute le projet, puis fait les étapes cochées. Rien n’est supprimé ni écrasé, et aucun processus n’est lancé : ils attendent dans l’onglet Processus.
Plus tard, quand un git pull modifie le fichier, la page du projet le signale et propose d’appliquer le changement : voir Appliquer le fichier.
Aucun serveur détecté ?
Ajoutez les domaines à la main : un sous-domaine (admin) ou un domaine complet, et un port. Vous pourrez toujours en ajouter plus tard dans l’onglet Domaines.
La page du projet
Une fois ajouté, le projet a sa page, avec ses onglets :
| Onglet | Raccourci | Contenu |
|---|---|---|
| Domaines | D | Domaines, cibles et état |
| Processus | P | Serveurs de dev et conteneurs lancés par Joppa |
| Environnement | E | Services liés et éditeur du .env |
| Runtime | R | Versions de Node, du gestionnaire de paquets et de PHP |
| Worktrees | W | Un environnement par worktree git |
| Analytics | S | Trafic, latence, erreurs et disponibilité |
| Inspecteur | Q | Les dernières requêtes, leurs en-têtes et leurs corps, et leur rejeu |
Le menu Actions (⋯) permet de Renommer… (avec l’option « Renommer aussi les domaines »), de Changer l’icône…, de Partager la configuration dans joppa.toml (voir joppa.toml), d’Afficher dans le Finder et de Retirer de Joppa. Retirer un projet arrête ses serveurs de dev et oublie sa configuration locale ; son dossier et son éventuel joppa.toml ne sont pas touchés.