Структура проекта

Настройка и конфигурация

Перед любым действием прочтите Перед началом работы и Основные сведения о терминале. В этих инструкциях предполагается, что вы открыли полный монорепозиторий supastack в VS Code; его корень package.json отмечает корень репозитория. В командах pnpm пакет рабочей области представляет собой папку приложения или общего кода; В продукте рабочее пространство — это контейнер данных и граница безопасности команды. corepack pnpm --filter ... выбирает один пакет из монорепозитория, пока команды выполняются из его корня. Если вы открыли только синхронизированную папку мобильного устройства или рабочего стола, она не содержит веб-серверной части, настройки Docker или корневых сценариев: запустите серверную часть из этого монорепозитория или доступного размещенного сервера и используйте собственные сценарии папки платформы. Переменная среды — это именованный параметр, хранящийся в локальном файле .env или на панели управления хостингом; перезапустите соответствующее приложение после его изменения и не допускайте попадания секретов сервера в значения NEXT_PUBLIC_ и EXPO_PUBLIC_.

1. Откройте корневой файл package.json в VS Code, затем найдите apps/web-tanstack для веб-сайта, apps/mobile для Expo, apps/desktop для оболочки рабочего стола и пакеты для общих частей.

2. Из корня репозитория запустите corepack pnpm --filter @supastack/web-tanstack dev.

3. Откройте http://localhost:3000. Ожидается: веб-приложение запускается с apps/web-tanstack, а общие пакеты остаются в том же репозитории; окно рабочего стола оборачивает это веб-приложение, а не содержит второй продукт.

Воркспейс pnpm содержит TanStack Start в apps/web-tanstack, Expo в apps/mobile и общие пакеты в packages. Запускайте команды воркспейса из корня репозитория. Маршруты приложений компонуют общие модули; продуктовое поведение принадлежит потребляющему продукту.

Прочитайте AGENTS.md и .ai/PROJECT_CONTEXT.md до изменения поведения. Файловые зеркала в .ai/ объясняют решения и ограничения, которые могут быть неочевидны из одного компонента.

apps/web-tanstack/src/    File routes, actions and framework wiring
packages/web-core/src/    Shared pages, components and server composition
apps/mobile/              Expo application
packages/                 Shared contracts and adapters
tests/                    Cross-module and browser checks
docs/                     Operational guides

Команды для копирования

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

corepack pnpm --filter @supastack/web-tanstack dev

Куда поместить изменение

Перед редактированием решите, какому приложению или пакету принадлежит изменение. Эмпирическое правило: если оно нужно только одной поверхности продукта — поместите его в это приложение; если нужно всем поверхностям — поместите в общий пакет внутри packages/.

Веб-репозиторий TanStack и монорепозиторий All Platforms содержат все папки ниже. Отдельная выгрузка Mobile или Desktop содержит только своё приложение — серверный код остаётся в веб-репозитории TanStack.

• Создайте первую функцию

• Новая маркетинговая или лендинг-страница → apps/web-tanstack/src/routes/ — публичный сайт.
• Новый экран внутри продукта после входа → apps/web-tanstack/src/routes/ для маршрута плюс packages/web-core/src/pages/ для его исходников load и view — страницы компонуют общие пакеты.
• Новый API-маршрут → apps/web-tanstack/src/routes/api/ — серверная половина веб-приложения.
• Изменение, общее для всех приложений — таблица базы данных, контракт, адаптер провайдера → соответствующая папка в packages/.
• Экран только для телефона → apps/mobile/ — он обращается к API веб-приложения, а не содержит собственный бэкенд.
• Поведение только для десктопа → apps/desktop/ — оболочка Tauri оборачивает веб-приложение и почти никогда не ответвляет продуктовый интерфейс.

Рабочий процесс внедрения

Начните с маршрута, владеющего действием пользователя, проследите его серверный обработчик, затем инспектируйте вызываемый общий пакет. UI-компонент не должен воссоздавать разрешение воркспейса, авторизацию биллинга или выбор провайдера.

Добавляя маршрут, решите, публичный он или аутентифицированный. Разрешайте аутентифицированное владение на сервере до доступа к записям пользователя и держите серверные креденшелы вне клиентских импортов.

Проверка и устранение неполадок

Если команда сообщает, что ни один проект не соответствует фильтру, убедитесь, что терминал находится в папке, содержащей корневой файл package.json. Если порт 3000 уже используется, сначала остановите другой локальный веб-сервер. Не ищите отдельную реализацию чата или входа в систему на рабочем столе; оболочка рабочего стола загружает веб-сервер.

Запускайте соответствующие тесты и проверку типов после изменения контракта пакета. Инспектируйте и веб-, и мобильных потребителей при изменении общих типов. Успешная веб-сборка сама по себе не устанавливает совместимость с нативным приложением.