Añadir un proyecto
Cómo Joppa analiza una carpeta, nombra el proyecto, encuentra sus servidores de desarrollo y les propone dominios.
Tres formas de añadir
- Arrastrar y soltar: suelta una carpeta en cualquier parte de la ventana («Suelta para añadir el proyecto»).
- Botón o atajo: + nuevo junto a Proyectos en la barra lateral, Añadir un proyecto en el inicio, o N desde cualquier sitio.
- Terminal: en el TUI, tecla a en la sección Proyectos, o la herramienta MCP
add_project.
La ventana Añadir un proyecto muestra lo que Joppa ha encontrado; no se guarda nada hasta que confirmas (⌘ ⏎).
El nombre y el icono
El nombre sale del campo name de package.json (sin el scope @org/) o, si no, del nombre de la carpeta. Se convierte a minúsculas sin acentos ni espacios: Kiné Santé se convierte en kine-sante.
El icono se genera a partir del nombre. Cámbialo cuando quieras con I en la página del proyecto: motivos generados, iniciales, pictogramas o tu propia imagen (.svg, .png, .jpg, .webp, 180 KB como máximo), tramada con los colores de Joppa.
Qué detecta Joppa
| Stack | Indicio | Puerto por defecto |
|---|---|---|
Vite, Vite+ (vp), React Router, Remix, SvelteKit |
script dev |
5173, o port: en vite.config |
| Astro | script dev |
4321, o port: en astro.config |
| Next.js | script dev |
3000 |
| Nuxt | script dev |
3000 |
| Angular, Nx (Angular, webpack) | ng serve, target de Nx |
4200 |
| Create React App, Docusaurus | react-scripts start, docusaurus start |
3000 |
| Vue CLI, Gatsby, Storybook, Expo | su comando | 8080, 8000, 6006, 8081 |
| Node (otro servidor) | puerto escrito en el script o en el código | el encontrado |
| Laravel | archivo artisan |
8000 (php artisan serve) |
| Symfony, otro PHP | public/index.php y composer.json |
8000 (php -S) |
| Bun | bun.lock / bun.lockb |
— |
| Docker Compose | compose.yaml, docker-compose.yml… |
puertos publicados |
Joppa lee el script dev de la raíz y de cada paquete de un monorepo: workspaces de npm, yarn o bun, pnpm-workspace.yaml, lerna.json, proyectos Nx. Un puerto se reconoce en estas formas: --port 3000, -p 3000, --port=3000, PORT=3000, ${PORT:-3000}. El detalle está en Procesos.
Para Laravel, el dominio base va a php artisan serve; el servidor de Vite, que solo sirve los assets, no recibe ninguno.
Los subdominios propuestos
Con un solo servidor, el proyecto recibe el dominio base: miproyecto.test. En un monorepo, cada app recibe un subdominio según el nombre de su carpeta:
| Carpeta de la app | Dominio |
|---|---|
web, app, frontend, client, dashboard |
app.miproyecto.test |
marketing, site, www, website, landing, home |
miproyecto.test |
api, server, backend |
api.miproyecto.test |
otra (docs, admin…) |
docs.miproyecto.test |
Si dos apps acaban con el mismo nombre, se numeran: app, app2.
Las interfaces web de Docker Compose
Los servicios de Compose que publican una interfaz web conocida también reciben su dominio:
| Servicio | Puerto | Dominio |
|---|---|---|
| Mailpit, MailHog | 8025 | mail.miproyecto.test |
| MinIO (consola) | 9001 | minio.miproyecto.test |
| RabbitMQ (management) | 15672 | rabbitmq.miproyecto.test |
| Adminer | 8080 | adminer.miproyecto.test |
| phpMyAdmin | 80 | phpmyadmin.miproyecto.test |
| pgAdmin | 80 | pgadmin.miproyecto.test |
Los demás puertos publicados (bases de datos, cachés) aparecen como «Sin enrutar (no son interfaces web)». Si el Compose contiene PostgreSQL, MySQL, MariaDB, Redis o Valkey, la ventana también propone importar sus datos en Joppa: consulta Importación desde Docker Compose.
Un repositorio con joppa.toml
Cuando la carpeta contiene un joppa.toml (la configuración que comparte un equipo), la ventana parte de él:
- el nombre es el de su sección
[project]; - los dominios son sus
[[domain]], con «joppa.toml» como origen mostrado; - bajo Configuración de equipo · joppa.toml, el plan lista el resto, un paso por línea: crear el servidor o reutilizar el de la máquina, crear la base de datos con sus extensiones, vincular el proyecto, escribir el
.env(Ver el diff), fijar Node, el gestor de paquetes y PHP, configurar los worktrees. Los pasos que ya están listos se pliegan bajo «ya listos».
Desmarca lo que no quieras: los pasos que dependen de ello se desmarcan con él. Un paso imposible aquí aparece en gris con el motivo: un motor reservado a Joppa Pro, un dominio que ya tiene otro proyecto. Las diferencias se señalan sin bloquear nada: un servidor PostgreSQL de la máquina en una versión distinta de la pedida se reutiliza, y un .node-version del repositorio prevalece sobre la sección [runtime].
Añadir y preparar (⌘ ⏎) añade el proyecto y luego hace los pasos marcados. No se elimina ni se sobrescribe nada, y no se inicia ningún proceso: esperan en la pestaña Procesos.
Más adelante, cuando un git pull modifica el archivo, la página del proyecto lo indica y propone aplicar el cambio: consulta Aplicar el archivo.
¿No se detectó ningún servidor?
Añade los dominios a mano: un subdominio (admin) o un dominio completo, y un puerto. Siempre podrás añadir más después en la pestaña Dominios.
La página del proyecto
Una vez añadido, el proyecto tiene su página, con sus pestañas:
| Pestaña | Atajo | Contenido |
|---|---|---|
| Dominios | D | Dominios, destinos y estado |
| Procesos | P | Servidores de desarrollo y contenedores iniciados por Joppa |
| Entorno | E | Servicios vinculados y editor del .env |
| Runtime | R | Versiones de Node, del gestor de paquetes y de PHP |
| Worktrees | W | Un entorno por worktree de git |
| Analytics | S | Tráfico, latencia, errores y disponibilidad |
| Inspector | Q | Las últimas peticiones, sus cabeceras y cuerpos, y su repetición |
El menú Acciones (⋯) permite Renombrar… (con la opción «Renombrar también los dominios»), Cambiar icono…, Compartir la configuración en joppa.toml (consulta joppa.toml), Mostrar en el Finder y Quitar de Joppa. Quitar un proyecto detiene sus servidores de desarrollo y olvida su configuración local; su carpeta y su joppa.toml, si lo hay, no se tocan.