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

Veritabanı migrasyonlarından veya uygulamayı çalıştırmadan önce .env.local dosyasını yapılandırın. Önce dosyayı oluşturun, ardından kurulum ilerledikçe bölüm bölüm değer ekleyin.

Yerel env dosyası oluştur

Örnek dosyayı 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

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

Kurulum~15 dk

Supabase kurulumu

Bu Supabase adımlarını sırayla tamamlayın — proje oluşturma, ortam değişkenleri ve veritabanı migrasyonu.

7 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

CLI bağlantısı ve API URL oluştururken kullanılacak.

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

Supabase ortam değişkenleri

Supabase projenizi oluşturduktan sonra .env.local dosyasına ekleyin — veritabanı migrasyonlarından önce.

NEXT_PUBLIC_SUPABASE_URL

Proje API URL'niz. YOURPROJECTID yerine gerçek Supabase Project ID'nizi yazın.

.env.local

NEXT_PUBLIC_SUPABASE_URL=https://YOURPROJECTID.supabase.co

Nerede bulunur

Supabase Panel → Project Settings → API

NEXT_PUBLIC_SUPABASE_ANON_KEY

Genel anon anahtar — tarayıcıda güvenle kullanılabilir. Panelden kopyalayın; yer tutucu kullanmayın.

Nerede bulunur

Supabase Panel → Project Settings → API

SUPABASE_SERVICE_ROLE_KEY

Yalnızca sunucu tarafı. İstemciye asla açmayın. Panelden kopyalayın; yer tutucu kullanmayın.

Nerede bulunur

Supabase Panel → Project Settings → API

Veritabanı kurulumu ve migrasyonlar

~15 dk

CLI kurulumu, bağlantı ve şema migrasyonu

3

Supabase CLI yükle

Global yükleyin, ardından doğrulayın:

Terminal

npm install -g supabase

Kurulumu doğrula:

Terminal

supabase --version

4

Supabase CLI'ye giriş yap

Kimlik doğrulama için bir tarayıcı penceresi açılır. Giriş yapın ve terminale dönün.

Terminal

supabase login

5

Yerel projeyi bağla

PROJECT_REF yerine 2. adımdaki Project ID'nizi yazın.

Terminal

supabase link --project-ref <PROJECT_REF>

Örnek:

Terminal

supabase link --project-ref abcdefghijklmnop

6

Veritabanı migrasyonlarını uygula

Tüm tabloları, fonksiyonları, politikaları ve seed verilerini oluşturur. Supabase kimlik bilgileri .env.local'de olmalıdır.

Terminal

supabase db push

7

Tabloların oluşturulduğunu doğrula

Devam etmeden önce şemanızın hazır olduğunu onaylayın.

Nerede bulunur: Supabase Panel → Project → Table Editor

Veritabanını güncelleme

Veritabanı değişiklikleri içeren repo güncellemelerini çektikten sonra:

Terminal

git pull
supabase db push

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

Ayrı bir terminalde olayları yerel webhook işleyicinize yönlendirin. İmza secret'ını STRIPE_WEBHOOK_SECRET'e kopyalayın:

Terminal

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

API anahtarları

Anahtarları Stripe panelinden .env.local dosyasına kopyalayın — depoda veya dokümantasyonda asla hardcode etmeyin.

Nerede bulunur

Stripe Panel → Developers → API Keys

Publishable Key (pk_test_...)
Secret Key (sk_test_...)

Ortam değişkenleri

STRIPE_SECRET_KEYZorunlu

Sunucu tarafı Stripe API anahtarı — panelden kopyalayın, asla hardcode etmeyin.

Nerede bulunur

Stripe Panel → Developers → API Keys — Secret key (sk_test_...)

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYZorunlu

Stripe.js checkout için istemci tarafı anahtar — panelden kopyalayın, asla hardcode etmeyin.

Nerede bulunur

Stripe Panel → Developers → API Keys — Publishable key (pk_test_...)

Webhook'lar

Adımlar

1Yerel geliştirme için stripe listen --forward-to localhost:3000/api/stripe/webhook çalıştırın ve webhook imza secret'ını kopyalayın
2Dağıtılmış ortamlar için webhook endpoint ekleyin: https://YOUR_APP_URL/api/stripe/webhook
3Olayları seçin: checkout.session.completed, customer.subscription.*, invoice.*, payment_method.*
4Webhook imza secret'ını .env.local içinde STRIPE_WEBHOOK_SECRET'e kopyalayın

Ortam değişkenleri

STRIPE_WEBHOOK_SECRETZorunlu

Stripe webhook imzalarını doğrular.

Nerede bulunur

Stripe Panel → Developers → Webhooks → Signing secret · Yerel: stripe listen çıktısı

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_EMAIL'i alan adınızda doğrulanmış bir adrese ayarlayı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_EMAILZorunlu

Doğrulanmış gönderici adresi (örn. noreply@alanadiniz.com).

Nerede bulunur

Resend Panel → Domains → Alan adı ekle → DNS doğrula → o alandaki bir adresi kullanın

Kurulum~2 dk

Hızlı başlangıç

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

Proje bağımlılıklarını yükle

Terminal

npm install

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

Geliştirme sunucusunu http://localhost:3000 adresinde başlat

Terminal

npm run dev

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
supabase db push	Veritabanı şemasını uygula (supabase db push)
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ı.

1Production Supabase'e şemayı uygulayın (supabase db push)
2Tüm env değişkenlerini Vercel'de ayarlayın — yukarıdaki Ortam kurulumu bölümünü kullanın
3Next.js uygulamasını dağıtın
4Stripe webhook kaydedin → https://UYGULAMA_URL/api/stripe/webhook
5Production'da super admin oluşturun ve sync:plans çalıştırın