Genel bakış

Production SaaS Starter, workspace tabanlı çok kiracılı bir platformdur — minimal bir demo değil. Gerçek kalıplar içerir: PostgreSQL RLS, SECURITY DEFINER RPC'ler, Stripe webhook idempotency, çift katmanlı RBAC ve servis sağlayıcı soyutlaması.

Üyelikler, davetler ve slug kapsamlı URL'lerle workspace'ler
Stripe abonelikleri, kullanım ölçümü, promosyon kodları ve kurumsal anlaşmalar
Denetim günlükleri ve kullanıcı/workspace moderasyonu ile platform admin konsolu
E-posta/şifre + OAuth, 2FA, Resend ile şifre sıfırlama

Stack: Next.js 16, React 19, Supabase, Stripe, Resend, 4 dil ile next-intl.

Kurulum~3 dk

Bağımlılıkları yükle

Ortam değişkenlerini yapılandırmadan önce proje kökünden npm paketlerini yükleyin.

Depoyu klonladıktan sonra bir kez çalıştırın:

Terminal

npm install

Ön koşul~5 dk

Ortam kurulumu

Uygulamayı çalıştırmadan önce .env.local dosyasını yapılandırın. Önce dosyayı oluşturun, ardından aşağıdaki kurulumu tamamladıkça bölüm bölüm değer ekleyin.

Yerel env dosyası oluştur

Devam etmeden önce proje kökünde .env.example → .env.local kopyalayın. Stripe ve Resend değerlerini aşağıdaki bölümlerde ekleyin. Supabase değişkenleri Supabase kurulum bölümünde yapılandırılır.

Terminal

cp .env.example .env.local

Windows: copy .env.example .env.local

Uygulama

Zorunlu

Dağıtılmış uygulama URL'niz — ödeme yönlendirmeleri, e-posta bağlantıları ve OAuth callback'leri için kullanılır.

Paneli aç Dokümantasyonu gör

Adımlar

1Yerel geliştirme için NEXT_PUBLIC_APP_URL=http://localhost:3000 ayarlayın
2Production için Vercel dağıtım URL'nizi veya özel alan adınızı kullanın
3Değişkeni Vercel → Proje → Ayarlar → Ortam Değişkenleri bölümüne ekleyin

Ortam değişkenleri

NEXT_PUBLIC_APP_URLZorunlu

SaaS uygulamanızın genel URL'si (sonunda / olmadan).

Nerede bulunur

Yerel: http://localhost:3000 · Production: Vercel proje alan adı veya özel domain

Örnek: https://app.alanadiniz.com

NEXT_PUBLIC_APP_NAME

İşlemsel e-postalarda gösterilen marka adı.

Nerede bulunur

Herhangi bir görünen ad seçin — harici servis gerekmez

Örnek: Acme SaaS

İzin verilen origin'ler

CSRF doğrulaması ve server action'lar için çapraz origin erişimini yapılandırın.

ALLOWED_ORIGINS

API'lere erişmesine izin verilen frontend alan adlarının virgülle ayrılmış listesi.

.env.local

ALLOWED_ORIGINS=

Tek origin

ALLOWED_ORIGINS=http://localhost:3000

Birden fazla origin

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

Kurulum~5 dk

Supabase kurulumu

Bu Supabase adımlarını sırayla tamamlayın — projenizi oluşturun, ardından ortam değişkenlerini ekleyin.

2 adım — sırayla tamamlayın

Supabase kurulumu

~5 dk

Projenizi oluşturun ve Project ID'nizi kopyalayın

1

Supabase projesi oluştur

supabase.com'da oturum açın, New project'e tıklayın, ad ve bölge seçin, veritabanı parolası belirleyin ve sağlanmayı bekleyin.

Supabase Panelini aç

2

Project ID'nizi kopyalayın

API URL'nizi oluştururken ve uygulamayı yapılandırırken bunu kullanacaksınız.

Nerede bulunur: Supabase Panel → Project → Project Settings → Project ID

Supabase ortam değişkenleri

Supabase projenizi oluşturduktan sonra bunları .env.local dosyasına ekleyin.

Her iki anahtar da aynı sayfada bulunur.

NEXT_PUBLIC_SUPABASE_URL

Proje API URL'niz.

Henüz proje oluşturmadıysanız:

https://supabase.com/dashboard/org adresine gidin
Organizasyonunuzu açın, bir proje oluşturun, ardından Project URL'yi kopyalayın.
Supabase Panel → Projenizi açın → Settings → API → Project URL

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://YOURPROJECTID.supabase.co

Nerede bulunur

Supabase Panel → Projenizi açın → Settings → API → Project URL

NEXT_PUBLIC_SUPABASE_ANON_KEY

İstemci tarafı Supabase Auth ve sorgular için genel anon anahtarı.

Nerede bulunur

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

SUPABASE_SERVICE_ROLE_KEY

Yalnızca sunucu tarafı service role anahtarı — istemciye asla açmayın.

Nerede bulunur

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

Super admin e-postası

Supabase kimlik bilgileri yapılandırıldıktan sonra ekleyin.

SUPER_ADMIN_EMAIL

Super admin izinleri alması gereken e-posta adresi.

.env.local

SUPER_ADMIN_EMAIL=

Örnek

SUPER_ADMIN_EMAIL=admin@example.com

Yapılandırma~15 dk

Stripe kurulumu

Stripe CLI

Geliştirme sırasında yerel kimlik doğrulama ve webhook yönlendirme için Stripe CLI kullanın.

1Resmi Stripe dokümantasyonundaki talimatlara göre Stripe CLI'yi yükleyin
2Platforma özel kurulum adımlarını tamamlayın
3Stripe kimlik doğrulama/giriş işlemini çalıştırın
4Kimlik doğrulamadan sonra yerel Stripe geliştirmesine devam edin

Stripe CLI kurulum rehberi

CLI'yi doğrula

login çalıştırın — Stripe hesabınızı bağlamak için bir tarayıcı penceresi açılır:

Terminal

stripe login

Webhook'ları yerelde yönlendir

Önce şunu çalıştırın:

Terminal

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

Ardından terminal çıktısındaki oluşturulan imza secret'ını (whsec_...) kopyalayın:

Terminal

whsec_xxxxx

.env.local dosyasına yapıştırın:

.env.local

STRIPE_WEBHOOK_SECRET=whsec_xxxxx

API anahtarları

Stripe Dashboard'u açın ve anahtarlarınızı .env.local dosyasına kopyalayın — depoda veya dokümantasyonda asla hardcode etmeyin.

Stripe Dashboard'u aç

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — Publishable key'i kopyalayın
STRIPE_SECRET_KEY — Secret key'i kopyalayın

Yapılandırma~10 dk

Resend kurulumu

Resend

Zorunlu

İşlemsel e-posta — davetler, 2FA OTP, şifre sıfırlama. Supabase yerleşik e-postası kullanılmaz.

Paneli aç Dokümantasyonu gör

Adımlar

1resend.com'da kayıt olun
2Gönderim alan adınızı ekleyin ve doğrulayın (DNS kayıtları)
3Bir API anahtarı oluşturun
4RESEND_FROM_DOMAIN değerini doğrulanmış gönderim alan adınıza ayarlayın (aşağıdaki Resend kurulumuna bakın)

Ortam değişkenleri

RESEND_API_KEYZorunlu

E-posta göndermek için API anahtarı.

Nerede bulunur

Resend Panel → API Keys → Create API Key

RESEND_FROM_DOMAIN

Doğrulanmış Resend alan adınızı içermelidir. Yalnızca kök/origin alan adını kullanın — alt alan adı değil.

.env.local

RESEND_FROM_DOMAIN=

Örnek

RESEND_FROM_DOMAIN=shipy.live

Kurulum~2 dk

Hızlı başlangıç

Yukarıdaki ortam, Supabase, Stripe ve Resend kurulumunu tamamladıktan sonra şunu çalıştırın:

Seed planlarını Stripe ile senkronize et — ağırlıklı olarak test ve Stripe planlarını veritabanıyla eşitlemek için

Terminal

npm run sync:plans

🎉 Tebrikler!

Her şey yapılandırıldı. Uygulamayı başlatın:

Terminal

npm run dev

Hazırsınız!

Referans~3 dk

Geliştirme ve production

Günlük geliştirme ile production derlemesini yerelde önizleme için farklı komutlar kullanın.

Geliştirme

Hot reload ile geliştirme sunucusunu başlatın:

Terminal

npm run dev

Production önizlemesi

Production ortamını yerelde önizleyin — uygulamayı derleyin, ardından production sunucusunu başlatın:

Terminal

npm run build

Terminal

npm run start

Referans

Komut referansı

Komut	Açıklama
npm run sync:plans	Seed planlarını Stripe ürün/fiyatlarıyla senkronize et
npm run dev	Geliştirme sunucusunu başlat
npm run build	Production derlemesi
npm run start	Production sunucusunu başlat (build sonrası)
npm run test	Jest birim testlerini çalıştır (yalnızca servisler)

Referans

Mimari

Katı çağrı sırası olan dört katman — agent'lar ve geliştiriciler aynı yolu izler:

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

Temel konumlar:

1

Katman 1

Sunum — src/app/, src/components/

2

Katman 2

Uygulama — server action'lar, createRequestContext(), RBAC guard'ları

3

Katman 3

Domain — src/modules/*/ *.service.ts (iş kuralları)

4

Katman 4

Veri — repository'ler + src/services/ üzerinden PostgreSQL RLS/RPC'ler

Referans

Çok kiracılık

Workspace kiracıdır — ayrı bir organizasyon tablosu yoktur.

Kiracı anahtarı: workspaces.id (UUID); URL'ler benzersiz slug kullanır
Üyelikler kullanıcıları owner, admin veya member rolleriyle workspace'lere bağlar
RLS politikaları workspace_id IN (kullanıcının üyelikleri) kuralını uygular

Platform admin'ler platform_admins tablosu üzerinden /admin'e erişir — super_admin, platform_admin veya platform_viewer rolleri.

Referans

Kimlik doğrulama ve yetkilendirme

Auth akışı: giriş → isteğe bağlı 2FA → onboarding (workspace yok) veya workspace paneli. Platform admin davetleri platform-onboarding'e yönlendirir.

Supabase Auth ile e-posta/şifre ve OAuth
E-posta OTP ile 2FA (Resend) — Supabase yerleşik e-postası değil
Token tabanlı akış ve hız sınırlama ile şifre sıfırlama

Workspace rolleri ve izinleri:

ownerfaturalama, workspace silme, tam üye yönetimi
adminüye davet etme/çıkarma, workspace ayarlarını güncelleme
memberokuma ve katılım — admin işlemi yok

Referans

Faturalama ve abonelikler

Workspace başına bir aktif abonelik, Stripe müşteri ve abonelik ID'lerine bağlı.

Yeni abonelikler için checkout; self-servis yönetim için portal
Orantılı yükseltmeler; dönem sonunda planlanan düşürmeler
Seed planlar: Starter ($29/ay), Pro ($39/ay), Enterprise (özel)
/api/stripe/webhook, idempotent stripe_events tablosu ile durumu senkronize eder

Dağıtım~15 dk

Dağıtım

Önerilen stack: Vercel (Next.js) + Supabase Cloud + Stripe webhook'ları.

1Tüm env değişkenlerini Vercel'de ayarlayın — yukarıdaki Ortam kurulumu bölümünü kullanın
2Next.js uygulamasını dağıtın
3Stripe webhook kaydedin → https://YOUR_APP_URL/api/stripe/webhook
4Super admin oluşturun ve production'da sync:plans çalıştırın