Launch MVP Stripe Next.js Supabase Template

The template uses a distributed architecture for automated transactional emails. It is critical to distinguish between environment variables used by the Next.js app (Vercel) and those used by the Supabase Edge Functions.

• Vercel (Next.js App): Handles the UI and API routes (/api/*). It uses .env.local or Vercel Environment Variables.
• Supabase (Database + Functions): Handles the database, triggers, and Edge Functions (Deno runtime). It uses Supabase Secrets, which are separate from Vercel environment variables.

Email Flow:

1. Event: User signs up (INSERT into public.users) or subscription changes.
2. Trigger: A PostgreSQL database trigger (using pg_net) detects the change.
3. Edge Function: The trigger calls a Supabase Edge Function.
4. API Route: The Edge Function calls the /api/email/send route in your Next.js app.
5. Provider: The API route uses Resend to deliver the email.

Follow these steps to set up Stripe for payments and subscription management:

1. Development Mode

• Ensure Test mode is enabled in your Stripe Dashboard.
• Use the test card number: 4242 4242 4242 4242.
• Create your products in the Product Catalog and set up Payment Links with trial periods if needed.

2. Required Keys

Map the following from your Stripe Dashboard (Test Mode) to your .env.local:

• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY (starts with pk_test_)
• STRIPE_SECRET_KEY (starts with sk_test_)
• NEXT_PUBLIC_STRIPE_BUTTON_ID (your specific Buy Button ID)

3. Webhook Configuration

• Add a webhook endpoint in Stripe: your_url/api/stripe/webhook.
• Subscribe to the following events:
  • customer.subscription.*
  • checkout.session.*
  • invoice.*
  • payment_intent.*
• Copy the Signing Secret and assign it to STRIPE_WEBHOOK_SECRET in your environment variables.

Edge Functions run on Supabase infrastructure and require their own environment variables (secrets) to function. Use the Supabase CLI to link your project and deploy the functions.

1. Install and Login:

   npm install -g supabase
   supabase login

2. Link Project:

   supabase link --project-ref YOUR_PROJECT_REF

3. Set Secrets (Required for Edge Functions):

   supabase secrets set APP_URL=https://your-vercel-app-url.vercel.app
   supabase secrets set RESEND_API_KEY=re_your_actual_key
   supabase secrets set INTERNAL_API_KEY=your_internal_key

4. Deploy Functions:

   supabase functions deploy send-welcome-email
   supabase functions deploy send-billing-email
   supabase functions deploy send-cancellation-email

Verification: Check the Edge Functions tab in the Supabase Dashboard for 'Active' status.

# Example deployment sequence
supabase link --project-ref my-project-id
supabase secrets set APP_URL=https://my-app.vercel.app
supabase secrets set RESEND_API_KEY=re_123
supabase secrets set INTERNAL_API_KEY=my_secret
supabase functions deploy send-welcome-email

To integrate Supabase with the template, perform the following:

1. Authentication Setup

• In the Supabase Dashboard, go to Authentication > Providers > Google.
• Add your GCP Client ID and Client Secret (obtained from the Google Cloud Platform Console).
• Update your Site URL and Redirect URLs in Supabase settings.

2. Database Setup

• Enable Row Level Security (RLS) for all tables.
• Create appropriate policies for authenticated users and service roles.
• Execute the following SQL trigger to automatically initialize user profiles, preferences, and trials when a new user authenticates via Supabase Auth:

CREATE OR REPLACE FUNCTION public.handle_new_user()
RETURNS trigger AS $$
BEGIN
  INSERT INTO public.users (id, email, created_at, updated_at, is_deleted)
  VALUES (NEW.id, NEW.email, NOW(), NOW(), FALSE);
  
  INSERT INTO public.user_preferences (user_id, has_completed_onboarding)
  VALUES (NEW.id, FALSE);
  
  INSERT INTO public.user_trials (user_id, trial_start_time, trial_end_time)
  VALUES (NEW.id, NOW(), NOW() + INTERVAL '48 hours');
  
  RETURN NEW;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON auth.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();

MCP enables AI assistants (like those in the Cursor editor) to interact directly with your Stripe and Supabase accounts for debugging and management.

To set it up:

1. Create your local configuration by copying the example: cp .cursor/mcp.json.example .cursor/mcp.json
2. Populate the mcp.json file with your credentials:
   • Stripe: Use your Stripe API test key in the STRIPE_SECRET_KEY environment variable.
   • Supabase: Use your Supabase access token (found in Project Settings > API) as a command-line argument --access-token.
   • GitHub (Optional): Use a GitHub Personal Access Token.
3. Security: Never commit .cursor/mcp.json to version control. It is gitignored by default.
4. Restart your Cursor editor to apply the changes.

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y", 
        "@stripe/mcp"
      ],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_51ABC123..."
      }
    },
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "sbp_1234abcd5678efgh..."
      ]
    }
  }
}

To start a new project using this template, follow these steps:

1. Clone the repository: It is recommended to clone the repo and start a fresh git history to avoid template history in your production app.
2. Install dependencies: Run npm install or yarn install.
3. Configure environment variables: Create a .env.local file based on the .env.example template.
4. Configure external services: Set up Supabase, Stripe, Resend, and Google Cloud Platform (GCP) as detailed in the configuration guides.
5. Run the development server: Use npm run dev or yarn dev and access the app at http://localhost:3000.

# Recommended: Clone and start fresh
git clone https://github.com/ShenSeanChen/launch-mvp-stripe-nextjs-supabase my-full-stack-app
cd my-full-stack-app
rm -rf .git
git init
git add .
git commit -m "Initial commit from LaunchMVP template"
git remote add origin https://github.com/YOUR_USERNAME/my-full-stack-app.git
git push -u origin main

# Install dependencies
npm install

# Start development server
npm run dev

Create a .env.local file in your project root. You must populate the following variables from your service providers:

Application URLs

• NEXT_PUBLIC_APP_URL: The base URL of your application.
• NEXT_PUBLIC_API_URL: The API endpoint URL.
• NEXT_PUBLIC_WS_URL: The WebSocket URL.

Supabase

• NEXT_PUBLIC_SUPABASE_URL: Your Supabase Project URL.
• NEXT_PUBLIC_SUPABASE_ANON_KEY: Your Supabase 'Publishable key'.
• SUPABASE_SERVICE_ROLE_KEY: Your Supabase 'Secret key'.

Stripe (Use TEST keys during development!)

• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: Your Stripe pk_test_ key.
• NEXT_PUBLIC_STRIPE_BUTTON_ID: Your Stripe Buy Button ID.
• STRIPE_SECRET_KEY: Your Stripe sk_test_ key.
• STRIPE_WEBHOOK_SECRET: Your Stripe webhook signing secret (whsec_).

Other Services

• OPENAI_API_KEY: Your OpenAI API key.
• RESEND_API_KEY: Your Resend API key.
• INTERNAL_API_KEY: A custom key for internal API security.
• NEXT_PUBLIC_POSTHOG_KEY: Your PostHog project API key.
• NEXT_PUBLIC_POSTHOG_HOST: Your PostHog host (e.g., https://app.posthog.com).

NEXT_PUBLIC_APP_URL=http://localhost:8000
NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_WS_URL=ws://localhost:8080

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# OpenAI
OPENAI_API_KEY=

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_
NEXT_PUBLIC_STRIPE_BUTTON_ID=buy_btn_
STRIPE_SECRET_KEY=sk_test_
STRIPE_WEBHOOK_SECRET=whsec_

# Email
RESEND_API_KEY=re_xxxxxxxxxxxx
INTERNAL_API_KEY=your_internal_api_key

# Analytics
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com