Добавление проекта

Три способа добавить проект

• Перетаскивание: перетащите папку в любое место окна («Отпустите, чтобы добавить проект»).
• Кнопка или сочетание клавиш: + новый рядом с Проекты на боковой панели, Добавить проект на главном экране или N в любом месте.
• Терминал: в TUI клавиша a в разделе «Проекты» или инструмент MCP add_project.

Окно Добавить проект спрашивает только самое необходимое: имя (от него образуется базовый домен), значок и среды выполнения. Всё остальное приходит с анализом, который открывается сразу после этого: только полное чтение проекта показывает, какие домены и сервисы ему нужны. Ничего не сохраняется, пока вы не подтвердите (⌘ ⏎).

Имя и значок

Имя берётся из раздела [project] файла joppa.toml, иначе из поля name в package.json (без scope @org/), иначе из имени папки. От него образуется базовый домен: monprojet.test. Имя переводится в нижний регистр, без диакритики и пробелов: Kiné Santé превращается в kine-sante.

Значок генерируется из имени. Его можно сменить в любой момент клавишей I на странице проекта: сгенерированные узоры, инициалы, пиктограммы или собственное изображение (.svg, .png, .jpg, .webp, не больше 180 КБ), растрированное в цветах Joppa.

Среды выполнения

Под именем блок Среды выполнения показывает, какая версия будет у каждого языка и почему.

PHP (папка с composer.json, artisan или .php-version). Joppa предлагает версию и объясняет выбор:

Показанная причина	Откуда берётся версия
.php-version требует 8.4.	Файл .php-version в папке или в одной из родительских папок
composer.json требует ^8.5	Самая новая версия, которую допускает ограничение require.php
Версия Joppa по умолчанию	Версия нигде не указана, а в Joppa уже есть версия по умолчанию
Самая новая	Версия нигде не указана: последняя

При необходимости выберите другую в списке. Флажок Скачать PHP … через Joppa установлен, если этой версии нет: она устанавливается сразу после нажатия Добавить, на шаге «Подготовка …», где видна каждая установка (PHP, затем Node и пакеты); проект открывается, когда всё готово. Записать .php-version закрепляет версию в папке, для всей команды. Без этого файла выбранная версия становится версией Joppa по умолчанию, если её у вас ещё не было.

Если PHP, который находит ваш shell, не запускается (удалённая установка Herd, отсутствующее расширение), Joppa сообщает об этом вместе с ошибкой. Процессы проекта в любом случае в первую очередь используют PHP из Joppa: см. Версии.

Node и пакеты (папка с package.json): версия Node, которую определяет Vite+, и файл, из которого она прочитана (.nvmrc, .node-version, package.json…), иначе текущая LTS; менеджер пакетов (npm, pnpm, yarn или bun) и его версия, прочитанные из поля packageManager или lock-файла. В каждой строке указано, скачана ли уже эта версия. При необходимости выберите другие в списках: Скачать и закрепить устанавливает их через Vite+ и записывает в папку (.node-version, packageManager); флажок установлен сразу, если чего-то не хватает.

Анализ

Флажок Проанализировать проект после добавления установлен по умолчанию: Добавить и проанализировать добавляет проект, при необходимости устанавливает его среды выполнения, затем открывает Что Joppa понял на его странице. Анализ идёт по шагам и показывает только те, где есть что предложить.

Если флажок снят, проект добавляется только с базовым доменом, без цели и без сервисов. На его странице остаётся баннер Чтобы начать, проанализируйте проект с кнопкой Проанализировать проект: без анализа всё равно не обойтись, чтобы запускать проект из Joppa.

1. joppa.toml

Если в папке есть joppa.toml (конфигурация, общая для команды), анализ начинается с него. Его план перечисляет по шагу на строку: домены из его [[domain]], создать сервер или использовать уже имеющийся на машине, создать базу данных с её расширениями, подключить проект, записать .env (Показать diff), закрепить Node, менеджер пакетов и PHP, настроить worktree, выполнить setup сервиса, база которого только что создана. Шаги, которые уже выполнены, свёрнуты под «Уже на месте».

Снимите флажки с того, что вам не нужно: зависящие шаги снимаются вместе с ними. Шаг, невозможный здесь, затенён и объясняет причину: движок, доступный только в Joppa Pro, домен, уже занятый другим проектом. О расхождениях Joppa сообщает, ничего не блокируя: сервер PostgreSQL на машине другой версии, чем запрошена, используется как есть, а .node-version из репозитория имеет приоритет над разделом [runtime].

Применить и продолжить выполняет отмеченные шаги и переходит дальше; Пропустить ничего не применяет. Ничего не удаляется и не перезаписывается. Если позже git pull изменит файл, страница проекта сообщит об этом: см. Применение файла.

2. Сервисы

Joppa перечисляет сервисы, которые использует проект, и предлагает вместо них сервисы Joppa: один сервер для всех ваших проектов, адрес которого записывается в .env.

• В Docker Compose: каждый сервис, который Joppa умеет заменить, с вариантами Оставить из Compose или Перейти на … из Joppa (выбран сразу). Данные PostgreSQL, MySQL, MariaDB, Redis и Valkey импортируются сразу после сохранения (см. Импорт из Docker Compose); Mailpit, MailHog, Typesense, Meilisearch, Reverb и Soketi переходят на Joppa без копирования данных (Soketi становится Reverb из Joppa).
• Найдены в файлах проекта: то, что выдают его .env, .env.example, composer.json, package.json, Prisma или Drizzle (см. Распознанные сервисы), с причиной под каждой строкой. Если флажок установлен, Joppa подключает проект к своему серверу этого движка или добавляет такой сервер, если его нет; сервер баз данных получает базу с именем проекта.

Снимите флажок с сервиса или выберите Оставить из Compose, и прямо под ним появится врезка: что дал бы вам сервис Joppa для этого движка. Адрес, записанный в .env и поддерживаемый в актуальном состоянии, журнал в реальном времени и ресурсы контейнера (см. Страница сервиса), а в зависимости от движка — база данных для каждого worktree, импорт, экспорт и копирование баз, входящие Mailpit прямо в Joppa или приложение для каждого проекта и журнал событий Reverb. Это ни к чему не обязывает: проект оставляет свой сервис. Использовать … из Joppa снова отмечает сервис одним щелчком.

Движок, доступный только в Joppa Pro, остаётся неотмеченным в бесплатной версии, со своим значком. Далее переходит к процессам; пока ничего не применено.

3. Процессы и домены

Таблица процессов: каждый сервер разработки, воркер или контейнер, его команда, порт и откуда взят этот порт. Столбец Домен даёт каждому процессу с портом поддомен базового домена: отметьте его и введите поддомен (пусто — для monprojet.test). Сервис Compose, заменённый сервисом Joppa, затенён: «заменяется сервисом Joppa».

Что распознаёт Joppa

Стек	Признак	Порт по умолчанию
Vite, Vite+ (vp), React Router, Remix, SvelteKit	скрипт dev	5173 или port: в vite.config
Astro	скрипт dev	4321 или port: в astro.config
Next.js	скрипт dev	3000
Nuxt	скрипт dev	3000
Angular, Nx (Angular, webpack)	ng serve, цель Nx	4200
Create React App, Docusaurus	react-scripts start, docusaurus start	3000
Vue CLI, Gatsby, Storybook, Expo	их команда	8080, 8000, 6006, 8081
Node (другой сервер)	порт, указанный в скрипте или в коде	найденный
Laravel	файл artisan	8000 (php artisan serve)
Symfony, другой PHP	public/index.php и composer.json	8000 (php -S)
Bun	bun.lock / bun.lockb	—
Docker Compose	compose.yaml, docker-compose.yml…	опубликованные порты

Joppa читает скрипт dev в корне и в каждом пакете монорепозитория: workspaces npm, yarn или bun, pnpm-workspace.yaml, lerna.json, проекты Nx. Порт распознаётся в таких формах: --port 3000, -p 3000, --port=3000, PORT=3000, ${PORT:-3000}. Подробности — в разделе Процессы.

Для Laravel базовый домен получает php artisan serve; сервер Vite, который отдаёт только ассеты, домена не получает.

Предлагаемые поддомены

Если сервер один, проект получает базовый домен: monprojet.test. В монорепозитории каждое приложение получает поддомен по имени своей папки:

Папка приложения	Домен
web, app, frontend, client, dashboard	app.monprojet.test
marketing, site, www, website, landing, home	monprojet.test
api, server, backend	api.monprojet.test
другое (docs, admin…)	docs.monprojet.test

Два приложения, которые получили бы одно и то же имя, нумеруются: app, app2.

Сервисы Compose, которые публикуют известный веб-интерфейс, тоже получают поддомен: Mailpit и MailHog (8025, mail, предлагается, но не отмечен, поскольку у Joppa есть свой Mailpit), консоль MinIO (9001, minio), RabbitMQ (15672, rabbitmq), Adminer (8080, adminer), phpMyAdmin и pgAdmin (80).

Если порт уже прослушивается на машине или зарезервирован другим проектом в Joppa, строка сообщает об этом и предлагает Использовать порт 5174 (первый следующий свободный порт). Проект резервирует свои порты, даже когда он остановлен, — и порты доменов, и порты процессов (5173 у Vite): сообщение называет проект и процесс и предлагает также Оставить 5173. Для порта, занятого программой вне Joppa, предлагается Остановить его (окно «Освободить порт»). См. Порт уже занят.

У проекта, подключённого к Reverb из Joppa, собственный процесс reverb не отмечен: его заменяет сервер Joppa.

Сохранить и запустить (или Сохранить) подключает выбранные сервисы, сохраняет процессы и домены, затем запускает импорт из Docker Compose, если он есть. Домены работают по HTTPS: в первый раз Joppa попросит включить сертификат и разрешение имён .test.

4. Тестовая база данных

Если тестам проекта Laravel нужна база данных, которую может предоставить Joppa (база PostgreSQL, объявленная в phpunit.xml, тесты на SQLite, хотя приложение работает на MySQL…), последний шаг Тестовая база данных показывает diff phpunit.xml или .env.testing. Создать и связать создаёт базу в сервисе Joppa и подключает к ней тесты; Пропустить оставляет всё как есть, а тот же блок остаётся во вкладке «Сервисы». См. Тестовая база данных.

Страница проекта

После добавления у проекта появляется своя страница с вкладками:

Вкладка	Клавиша	Содержимое
Домены	D	Домены, цели и состояние
Процессы	P	Серверы разработки и контейнеры, запущенные Joppa
Сервисы	V	Подключённые сервисы Joppa (PostgreSQL, Redis…) и тестовая база данных
Скрипты	X	Скрипты из package.json, Makefile… для запуска одним щелчком
Окружение	E	Переменные, которыми управляет Joppa, и редактор .env
Среда выполнения	R	Версии Node, менеджера пакетов и PHP
Worktrees	W	Отдельное окружение для каждого git worktree
Аналитика	S	Трафик, задержка, ошибки и доступность
Инспектор	Q	Последние запросы, их заголовки и тела, и их повтор

Меню Действия (⋯) позволяет Переименовать… (с параметром «Переименовать и домены»), Изменить значок…, Поделиться конфигурацией в joppa.toml (см. joppa.toml), Показать в Finder и Убрать из Joppa…. Если убрать проект, его серверы разработки останавливаются, а его локальная конфигурация забывается вместе с окружениями его worktree; папка проекта и его joppa.toml, если он есть, не затрагиваются.

Перед удалением Joppa спрашивает, что делать с данными, которые проект оставил в ваших сервисах; изначально отмечено всё:

• Базы данных к удалению: база проекта на каждом сервере PostgreSQL, MySQL или MariaDB, базы, созданные для его worktree, и, для проекта Laravel, его тестовая база (та, которую phpunit.xml или .env.testing указывает в сервисе Joppa, с пометкой «тесты»). Остановленный сервер запускается, чтобы удалить её. С Joppa Pro непосредственно перед этим делается снимок каждой базы.
• Его данные в сервисах: то, что проект оставил в Redis, Valkey, Mailpit, Typesense или Meilisearch. У этих серверов нет отдельного пространства для каждого проекта, поэтому Joppa распознаёт данные проекта по его .env:
  • проект Laravel хранит свои ключи Redis и Valkey под префиксом (REDIS_PREFIX, иначе <APP_NAME>_database_), а индексы Typesense и Meilisearch — под SCOUT_PREFIX: удаляются только они;
  • без префикса сервер, которым пользуется только этот проект, очищается полностью (все ключи, все письма, все индексы);
  • сервер, общий с другим проектом, без собственного префикса этого проекта, показан затенённым, и в нём ничего не удаляется.

Сами серверы остаются в Joppa и продолжают работать, даже если в них больше нет ни баз, ни данных; удалить сервис можно на его странице. База данных, которой пользуется и другой проект, показана затенённой и сохраняется. Снимите все флажки, чтобы убрать проект, не трогая данные.