Add a project
How Joppa analyzes a folder, names the project, finds its dev servers and suggests domains for them.
Three ways to add one
- Drag and drop: drop a folder anywhere on the window (“› Drop the folder to add it”).
- Button or shortcut: + new next to Projects in the sidebar, Add a project on the home screen, or N anywhere.
- Terminal: in the TUI, the a key on the Projects section, or the
add_projectMCP tool.
The Add a project window shows what Joppa found; nothing is saved until you confirm (⌘ ⏎).
Name and icon
The name comes from the name field of package.json (without the @org/ scope), otherwise from the folder name. It’s converted to lowercase, without accents or spaces: Kiné Santé becomes kine-sante.
The icon is generated from the name. Change it any time with I on the project page: generated patterns, initials, pictograms, or your own image (.svg, .png, .jpg, .webp, 180 KB max), dithered in Joppa’s colors.
What Joppa detects
| Stack | Clue | Default port |
|---|---|---|
Vite, Vite+ (vp), React Router, Remix |
dev script |
5173, or port: in vite.config |
| Astro | dev script |
4321, or port: in astro.config |
| Next.js | dev script |
3000 |
| Nuxt | dev script |
3000 |
| Node (other server) | port written in the script | the script’s port |
| Laravel | artisan file |
8000 |
| Bun | bun.lock / bun.lockb |
— |
| Docker Compose | compose.yaml, docker-compose.yml… |
published ports |
Joppa reads the dev script at the root and in every workspace of a monorepo. A port is recognized in these forms: --port 3000, -p 3000, --port=3000, PORT=3000, ${PORT:-3000}.
Suggested subdomains
With a single server, the project gets the base domain: myproject.test. In a monorepo, each app gets a subdomain based on its folder name:
| App folder | Domain |
|---|---|
web, app, frontend, client, dashboard |
app.myproject.test |
marketing, site, www, website, landing, home |
myproject.test |
api, server, backend |
api.myproject.test |
other (docs, admin…) |
docs.myproject.test |
Two apps that would end up with the same name are numbered: app, app2.
Docker Compose web interfaces
Compose services that publish a known web interface get their own domain too:
| Service | Port | Domain |
|---|---|---|
| Mailpit, MailHog | 8025 | mail.myproject.test |
| MinIO (console) | 9001 | minio.myproject.test |
| RabbitMQ (management) | 15672 | rabbitmq.myproject.test |
| Adminer | 8080 | adminer.myproject.test |
| phpMyAdmin | 80 | phpmyadmin.myproject.test |
| pgAdmin | 80 | pgadmin.myproject.test |
Other published ports (databases, caches) are listed as “Not routed (not web interfaces)”. If the Compose file contains PostgreSQL, MySQL, MariaDB, Redis or Valkey, the window also offers to import their data into Joppa: see Import from Docker Compose.
No server detected?
Add the domains by hand: a subdomain (admin) or a full domain, and a port. You can always add more later in the Domains tab.
The project page
Once added, the project has its own page, with these tabs:
| Tab | Shortcut | Contents |
|---|---|---|
| Domains | D | Domains, targets and status |
| Processes | P | Dev servers and containers started by Joppa |
| Environment | E | Linked services and the .env editor |
| Runtime | R | Node, package manager and PHP versions |
| Analytics | S | Traffic, latency, errors and uptime |
The Actions menu (⋯) lets you Rename… (with the “Rename the domains too” option), Change icon…, Show in Finder and Remove from Joppa. Removing a project stops its dev servers and forgets its local configuration; its folder and any joppa.toml are left untouched.