Обзор

Production SaaS Starter — workspace-based multi-tenant платформа, а не минимальное demo. Включает реальные паттерны: PostgreSQL RLS, SECURITY DEFINER RPCs, Stripe webhook idempotency, dual RBAC и service-provider abstraction.

Workspaces с memberships, invites и slug-scoped URLs
Stripe subscriptions, usage metering, promo codes и enterprise deals
Platform admin console с audit logs и модерацией users/workspaces
Email/password + OAuth, 2FA, password reset через Resend

Stack: Next.js 16, React 19, Supabase, Stripe, Resend, next-intl с 4 локалями.

Настройка~3 мин

Установка зависимостей

Установите npm-пакеты из корня проекта перед настройкой переменных окружения.

Выполните один раз после клонирования репозитория:

Терминал

npm install

Предварительно~5 мин

Настройка окружения

Настройте .env.local перед запуском приложения. Сначала создайте файл, затем добавляйте значения по мере прохождения setup ниже.

Создайте локальный env-файл

Скопируйте .env.example → .env.local в корне проекта перед продолжением. Добавьте значения Stripe и Resend в разделах ниже. Переменные Supabase настраиваются в разделе Supabase setup.

Терминал

cp .env.example .env.local

Windows: copy .env.example .env.local

Приложение

Обязательно

URL развёрнутого приложения — для редиректов checkout, email-ссылок и OAuth callbacks.

Открыть панель Документация

Шаги

1Для локальной разработки: NEXT_PUBLIC_APP_URL=http://localhost:3000
2Для production: URL деплоя Vercel или custom domain
3Добавьте переменную в Vercel → Project → Settings → Environment Variables

Переменные окружения

NEXT_PUBLIC_APP_URLОбязательно

Публичный URL SaaS-приложения (без завершающего /).

Где найти

Локально: http://localhost:3000 · Production: домен проекта Vercel или custom domain

Пример: https://app.yourdomain.com

NEXT_PUBLIC_APP_NAME

Название бренда в транзакционных письмах.

Где найти

Любое отображаемое имя — внешний сервис не нужен

Пример: Acme SaaS

Разрешённые origins

Настройте cross-origin доступ для CSRF-проверки и server actions.

ALLOWED_ORIGINS

Список frontend-доменов через запятую, которым разрешён доступ к API.

.env.local

ALLOWED_ORIGINS=

Один origin

ALLOWED_ORIGINS=http://localhost:3000

Несколько origins

ALLOWED_ORIGINS=http://localhost:3000,https://example.com

Настройка~5 мин

Настройка Supabase

Выполните эти шаги Supabase по порядку — создайте проект, затем добавьте переменные окружения.

2 шага — выполнить по порядку

Настройка Supabase

~5 мин

Создайте проект и скопируйте Project ID

1

Создать проект Supabase

Войдите на supabase.com, нажмите New project, выберите имя и регион, задайте пароль БД и дождитесь provisioning.

Открыть Supabase Dashboard

2

Скопировать Project ID

Вы будете использовать его при построении API URL и настройке приложения.

Где найти: Supabase Dashboard → Project → Project Settings → Project ID

Переменные окружения Supabase

Добавьте в .env.local после создания проекта Supabase.

Оба ключа находятся на одной странице.

NEXT_PUBLIC_SUPABASE_URL

URL API вашего проекта.

Если вы ещё не создали проект:

Перейдите на https://supabase.com/dashboard/org
Откройте организацию, создайте проект, затем скопируйте Project URL.
Supabase Dashboard → Откройте проект → Settings → API → Project URL

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://YOURPROJECTID.supabase.co

Где найти

Supabase Dashboard → Откройте проект → Settings → API → Project URL

NEXT_PUBLIC_SUPABASE_ANON_KEY

Публичный anon key для client-side Supabase Auth и запросов.

Где найти

Supabase Dashboard → Project Settings → API Keys → Legacy API Keys → anon public

SUPABASE_SERVICE_ROLE_KEY

Только server-side service role key — никогда не раскрывайте клиенту.

Где найти

Supabase Dashboard → Project Settings → API Keys → Legacy API Keys → service_role

Email super admin

Добавьте после настройки учётных данных Supabase.

SUPER_ADMIN_EMAIL

Email-адрес, которому должны быть назначены права super admin.

.env.local

SUPER_ADMIN_EMAIL=

Пример

SUPER_ADMIN_EMAIL=admin@example.com

Конфигурация~15 мин

Настройка Stripe

Stripe CLI

Используйте Stripe CLI для локальной аутентификации и пересылки webhooks при разработке.

1Установите Stripe CLI по инструкциям из официальной документации Stripe
2Завершите платформенные шаги установки
3Выполните аутентификацию/вход Stripe
4После аутентификации продолжите локальную разработку со Stripe

Руководство по установке Stripe CLI

Аутентифицировать CLI

Выполните login — откроется браузер для подключения аккаунта Stripe:

Терминал

stripe login

Пересылать webhooks локально

Сначала выполните:

Терминал

stripe listen --forward-to localhost:3000/api/stripe/webhook

Затем скопируйте сгенерированный signing secret (whsec_...) из вывода терминала:

Терминал

whsec_xxxxx

Вставьте его в .env.local:

.env.local

STRIPE_WEBHOOK_SECRET=whsec_xxxxx

API keys

Откройте Stripe Dashboard и скопируйте ключи в .env.local — никогда не hardcode ключи в репозитории или документации.

Открыть Stripe Dashboard

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — скопируйте Publishable key
STRIPE_SECRET_KEY — скопируйте Secret key

Конфигурация~10 мин

Настройка Resend

Resend

Обязательно

Транзакционная почта — приглашения, 2FA OTP, сброс пароля. Встроенная почта Supabase не используется.

Открыть панель Документация

Шаги

1Зарегистрируйтесь на resend.com
2Добавьте и верифицируйте sending domain (DNS-записи)
3Создайте API key
4Установите RESEND_FROM_DOMAIN на верифицированный домен отправки (см. настройку Resend ниже)

Переменные окружения

RESEND_API_KEYОбязательно

API key для отправки писем.

Где найти

Resend Dashboard → API Keys → Create API Key

RESEND_FROM_DOMAIN

Должен содержать ваш верифицированный домен Resend. Используйте только корневой/origin-домен — не поддомен.

.env.local

RESEND_FROM_DOMAIN=

Пример

RESEND_FROM_DOMAIN=shipy.live

Настройка~2 мин

Быстрый старт

После завершения настройки окружения, Supabase, Stripe и Resend выше выполните:

Синхронизировать seed-планы со Stripe — в основном для тестирования и синхронизации планов Stripe с базой данных

Терминал

npm run sync:plans

🎉 Поздравляем!

Всё настроено. Запустите приложение:

Терминал

npm run dev

Вы готовы к работе!

Справочник~3 мин

Разработка и production

Разные команды для ежедневной разработки и локального предпросмотра production-сборки.

Разработка

Запустите dev-сервер с hot reload:

Терминал

npm run dev

Production preview

Предпросмотр production-окружения локально — соберите приложение, затем запустите production-сервер:

Терминал

npm run build

Терминал

npm run start

Справочник

Справочник скриптов

Команда	Описание
npm run sync:plans	Синхронизировать seed-планы с продуктами/ценами Stripe
npm run dev	Запустить dev-сервер
npm run build	Production-сборка
npm run start	Запустить production-сервер (после build)
npm run test	Запустить Jest unit-тесты (только services)

Справочник

Архитектура

Четыре слоя со строгим порядком вызовов — agents и разработчики следуют одному пути:

UI → Server Actions / API → Services → Repositories → PostgreSQL (RLS/RPC)

Ключевые расположения:

1

Слой 1

Presentation — src/app/, src/components/

2

Слой 2

Application — server actions, createRequestContext(), RBAC guards

3

Слой 3

Domain — src/modules/*/ *.service.ts (business rules)

4

Слой 4

Data — repositories + PostgreSQL RLS/RPCs через src/services/

Справочник

Multi-tenancy

Workspace — это tenant; отдельной таблицы organization нет.

Tenant key: workspaces.id (UUID); URLs используют уникальный slug
Memberships связывают users с workspaces в ролях owner, admin или member
RLS policies enforce workspace_id IN (memberships пользователя)

Platform admins получают доступ к /admin через platform_admins — роли super_admin, platform_admin или platform_viewer.

Справочник

Аутентификация и авторизация

Auth flow: login → optional 2FA → onboarding (нет workspace) или workspace dashboard. Platform admin invites ведут на platform-onboarding.

Email/password и OAuth через Supabase Auth
2FA через email OTP (Resend) — не встроенная почта Supabase
Password reset с token-based flow и rate limiting

Workspace roles и permissions:

ownerbilling, удаление workspace, полное управление members
admininvite/remove members, обновление настроек workspace
memberчтение и участие — без admin-действий

Справочник

Billing и подписки

Одна активная подписка на workspace, привязанная к Stripe customer и subscription IDs.

Checkout для новых подписок; portal для self-serve управления
Upgrades с proration; downgrades запланированы на конец периода
Seed plans: Starter ($29/mo), Pro ($39/mo), Enterprise (custom)
Webhook на /api/stripe/webhook синхронизирует state с idempotent stripe_events table

Деплой~15 мин

Деплой

Рекомендуемый stack: Vercel (Next.js) + Supabase Cloud + Stripe webhooks.

1Установите все env vars в Vercel — см. раздел Environment setup выше
2Deploy Next.js app
3Зарегистрируйте Stripe webhook → https://YOUR_APP_URL/api/stripe/webhook
4Bootstrap super admin и sync:plans в production