/init-saas — Bootstrap a New SaaS Project

Scaffolds a complete Next.js + Supabase + Stripe SaaS project from a spec file or description.

Prerequisites

• Supabase Cloud project — Create one at supabase.com before running this skill
• Supabase MCP server — Must be configured in .mcp.json (the plugin ships with it). This is required for agents to interact with your Supabase project (migrations, RLS, type generation)
• Stripe account — Required if the project includes billing

Before starting, verify the Supabase MCP connection by using any mcp__supabase__* tool. If it prompts for authentication, complete the browser login flow first.

Input

The user provides either:

• A spec file path (read it first)
• A project description in the message

Extract: project name, core features, data model, billing requirements.

Steps

1. Create Next.js app

npx create-next-app@latest [project-name] --typescript --tailwind --eslint --app --src-dir --no-import-alias

2. Install SaaS dependencies

npm install @supabase/supabase-js @supabase/ssr stripe @supabase/stripe-sync-engine zod
npm install -D supabase

3. Create Supabase clients

Create the three client patterns from the /auth skill:

• src/lib/supabase/server.ts — Server Component / Server Action client using createServerClient from @supabase/ssr
• src/lib/supabase/client.ts — Browser client using createBrowserClient from @supabase/ssr
• src/lib/supabase/middleware.ts — Middleware client with session refresh and auth guard

4. Create middleware

Create src/middleware.ts that calls updateSession from the middleware client. Protect /dashboard and other app routes.

5. Create Stripe client

Create src/lib/stripe/client.ts:

import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
  typescript: true,
});

6. Set up folder structure

src/
├── app/
│   ├── (marketing)/        # Public pages
│   ├── (auth)/              # Auth pages
│   └── (app)/               # Protected dashboard
├── components/{ui,marketing,auth,app,shared}/
├── lib/{supabase,stripe}/
├── hooks/
├── types/
├── actions/
└── middleware.ts

7. Initial database migrations via MCP Supabase

Run migrations directly on the Supabase Cloud project via mcp__supabase SQL execution. Create core SaaS tables:

• profiles — id (references auth.users), full_name, avatar_url, stripe_customer_id, timestamps
• organizations — id, name, slug (unique), stripe_customer_id, timestamps
• org_members — id, org_id (FK), user_id (FK), role (check: owner/admin/member), timestamps, unique(org_id, user_id)

No custom subscriptions table needed — use @supabase/stripe-sync-engine instead, which creates a stripe schema with subscriptions, customers, products, prices, invoices, and more, all auto-synced via webhooks.

Enable RLS on all tables. Add basic policies:

• profiles: users can read/update own profile
• organizations: members can read their orgs
• org_members: members can read memberships in their orgs

Grant read access to the stripe schema for the authenticated role.

Add trigger: auto-create profile on auth.users insert.

7b. Stripe Sync Engine Edge Function

Deploy stripe-sync-engine as Supabase Edge Function via MCP Supabase: create supabase/functions/stripe-sync/index.ts with StripeSync webhook handler, set secrets (DATABASE_URL, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET) via MCP. Follow /stripe-setup skill patterns.

7c. RLS on stripe.* schema

Add RLS policies on stripe.* schema so users can only read their own Stripe data (join stripe.customer to profiles.stripe_customer_id).

8. Initialize shadcn/ui

npx shadcn@latest init -d

9. Create .env.example

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_SITE_URL=http://localhost:3000

10. Generate project CLAUDE.md

Create a CLAUDE.md in the project root with:

• Tech stack summary (Next.js App Router, Supabase, Stripe, shadcn/ui)
• File structure overview
• Key conventions (Server Actions for mutations, RLS-first, @supabase/ssr patterns)
• Database schema summary

11. Generate TASKS.md

Based on the spec, create a TASKS.md with all phases and tasks needed to build the full application. Follow the project-manager agent's TASKS.md format with phases 0-7.

Output

After completion, present:

• List of created files
• Next steps (set up Supabase project, add env vars, run /build to start building)
• Any spec items that need clarification

Rules

• Use App Router (not Pages Router)
• Use src/ directory
• Use @supabase/ssr (never @supabase/supabase-js directly for client creation)
• Use getUser() not getSession() for auth checks
• Enable RLS on every table
• Do NOT commit .env files — only create .env.example