StormCom - Multi-Tenant SaaS Platform

A production-ready Next.js 16 SaaS boilerplate with authentication, multi-tenancy, team management, and beautiful UI components built with shadcn/ui.

🚀 Features

Core Features

• ✅ Next.js 16 with App Router and React 19
• ✅ TypeScript for type safety
• ✅ Turbopack for blazing fast builds
• ✅ React Compiler for automatic memoization
• ✅ Tailwind CSS v4 with shadcn/ui components
• ✅ Vercel Analytics for performance monitoring

Authentication & Security

• ✅ NextAuth.js v4 with email magic links
• ✅ Prisma ORM with SQLite (dev) / PostgreSQL (prod)
• ✅ Session Management with JWT strategy
• ✅ Security Headers via proxy.ts
• ✅ Rate Limiting for API protection
• ✅ Environment Validation with Zod

Multi-Tenancy

• ✅ Organization Management with slug-based routing
• ✅ Role-Based Access Control (OWNER, ADMIN, MEMBER, VIEWER)
• ✅ Team Invitations via email
• ✅ Multi-Tenant Database with proper isolation

Integrations

• ✅ Facebook Login for Business - OAuth integration for commerce
• ✅ Facebook Commerce Platform - Webhook support for orders and catalogs
• ✅ Encrypted Token Storage - Secure credential management

UI/UX

• ✅ 30+ shadcn/ui Components pre-configured
• ✅ Dark Mode with next-themes
• ✅ Toast Notifications with Sonner
• ✅ Responsive Design mobile-first approach

📦 Tech Stack

Category	Technology
Framework	Next.js 16.0.3
UI Library	React 19.2
Language	TypeScript 5
Styling	Tailwind CSS v4
Components	shadcn/ui
Authentication	NextAuth.js 4.24
Database	Prisma 6.19
Email	Resend

🚦 Getting Started

Installation

1. Clone and install:

npm install

2. Set up environment variables in .env.local:

DATABASE_URL=\"file:./dev.db\"
NEXTAUTH_URL=\"http://localhost:3000\"
NEXTAUTH_SECRET=\"your-secret-min-32-chars\"
RESEND_API_KEY=\"re_your_key\"
EMAIL_FROM=\"noreply@yourdomain.com\"

3. Generate Prisma Client and run migrations:

npm run prisma:generate
export $(cat .env.local | xargs) && npm run prisma:migrate:dev

4. Start development:

npm run dev

🔌 Facebook Integration Setup

Prerequisites

1. Facebook App: Create a Facebook App at developers.facebook.com
2. App Review: Submit for App Review to access production features
3. Permissions Required:
   • public_profile (default)
   • email (default)
   • pages_read_engagement (for page access)
   • pages_manage_metadata (for page management)
   • catalog_management (for product catalogs)
   • business_management (for business assets)

Environment Variables

Add these to your .env.local:

# Facebook Integration
FACEBOOK_APP_ID="your-app-id"
FACEBOOK_APP_SECRET="your-app-secret"
FACEBOOK_WEBHOOK_VERIFY_TOKEN="random-string-for-verification"
ENCRYPTION_KEY="generate-with-openssl-rand-hex-32"

Generate Encryption Key:

openssl rand -hex 32

OAuth Flow

1. Start OAuth: Redirect users to /api/auth/facebook/start?tenant=STORE_ID
2. User Authorization: Facebook prompts user to grant permissions
3. Callback: System exchanges code for long-lived token (60 days)
4. Asset Discovery: Automatically discovers connected pages, catalogs, and business
5. Storage: Encrypts and stores token with tenant isolation

Webhook Configuration

1. Configure in Facebook App Dashboard:

   • Webhook URL: https://your-domain.com/api/facebook/webhook
   • Verify Token: Use value from FACEBOOK_WEBHOOK_VERIFY_TOKEN

2. Subscribe to Events:

   • commerce_orders - Order status updates
   • page - Page and catalog updates
   • feed - Product feed changes

3. Verify Signature: All webhooks verify X-Hub-Signature-256 header

Multi-Tenant Isolation

• Each Facebook connection is scoped to a specific Store (tenant)
• State parameter includes signed tenant ID for CSRF protection
• Tokens encrypted at rest using AES-256-GCM
• Query filters always include storeId to prevent data leakage

Testing

# Start OAuth flow (replace with actual store ID)
curl "http://localhost:3000/api/auth/facebook/start?tenant=YOUR_STORE_ID"

# Test webhook verification
curl "http://localhost:3000/api/facebook/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123"

🚀 Deployment

Deploy to Vercel

🎉 Automatic Database Migration - The deployment process now handles PostgreSQL migrations automatically!

1. Prepare Database: Set up a PostgreSQL database (Vercel Postgres recommended)

2. Configure Environment Variables in Vercel:

   • DATABASE_URL - PostgreSQL connection string
   • NEXTAUTH_SECRET - Generate with openssl rand -base64 32
   • NEXTAUTH_URL - Your production URL (e.g., https://your-app.vercel.app)
   • EMAIL_FROM - Sender email address
   • RESEND_API_KEY - Email service API key

3. Deploy:

   # Via GitHub (recommended)
   # Push to GitHub and import in Vercel dashboard
   
   # Or via CLI
   vercel --prod

4. That's it! Database migrations run automatically during build. No manual migration steps required.

What happens during deployment:

• ✅ Install dependencies
• ✅ Run PostgreSQL migrations automatically (scripts/migrate-postgres.js)
• ✅ Generate Prisma Client for PostgreSQL
• ✅ Create all database tables and indexes
• ✅ Build Next.js application

Optional: Seed Demo Data

Option 1: Automatic Seeding During Deployment

To enable automatic seeding of demo data during Vercel deployment:

1. Set SEED_DATABASE=true in Vercel environment variables (Project Settings → Environment Variables)
2. Deploy or redeploy
3. Important: Remove or set SEED_DATABASE=false after seeding to prevent accidental future seeding

⚠️ WARNING: Seeding deletes all existing data. Only use on fresh databases.

See Production Seeding Guide for detailed instructions.

Option 2: Manual Seeding

To populate your production database with demo data manually:

vercel env pull .env.local
export $(cat .env.local | xargs)
npm run prisma:seed:production

Demo Login: test@example.com / Test123!@#

See VERCEL_DEPLOYMENT.md for detailed instructions and troubleshooting.

📚 Documentation

• Deployment Guide - Deploy to Vercel with PostgreSQL
• Production Seeding - Seed production database with demo data
• PostgreSQL Migration Guide - Migrate from SQLite to PostgreSQL
• Development Guide - Implementation guidance
• Copilot Instructions - Detailed project structure

For Next.js 16 specifics, see official documentation at https://nextjs.org/docs

Built with Next.js 16 and shadcn/ui

npm run prisma:generate # Generate Prisma Client npm run prisma:migrate # Run migrations (dev) npm run prisma:reset # Reset database npm run prisma:push # Push schema changes npm run prisma:seed # Seed database npm run prisma:studio # Open Prisma Studio npm run db:seed # Alias for prisma:seed

🔑 Super Admin Credentials: Email: superadmin@example.com Password: SuperAdmin123!@#

🔑 Test User Credentials (Password: Test123!@#):
Owner: owner@example.com (Password: Test123!@#) Admin: admin@example.com Member: member@example.com Primary Store ID: cmiz4k6ad000dfmrcpwawd3by
Secondary Store ID: cmiz4k6ae000ffmrco99lczvs

"buildCommand": "node scripts/migrate-postgres.js && node scripts/conditional-seed.js && npm run build", "outputDirectory": ".next", "$schema": "https://openapi.vercel.sh/vercel.json", "framework": "nextjs", "installCommand": "npm install" "buildCommand": "npm run vercel-build",