Stripe SDK Setup

Stripe provides official SDKs for both server and browser environments. The server SDK handles secure operations like creating checkout sessions, while the browser SDK redirects users to Stripe's hosted checkout page. This lesson sets up both.

Outcome

Configure the Stripe SDK for both server and browser environments, ready to process subscriptions.

Fast Track

1. Create a Stripe account at stripe.com and get API keys
2. Add STRIPE_SECRET_KEY and NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY to .env.local
3. Implement utils/stripe/config.ts and utils/stripe/client.ts

Hands-on Exercise 2.1

Configure the Stripe SDK to work in your app:

Requirements:

1. Create a Stripe account and access test mode API keys
2. Add secret and publishable keys to environment variables
3. Create a server-side Stripe client with proper configuration
4. Create a browser-side Stripe loader for checkout redirects

Implementation hints:

• The server SDK uses your secret key (never expose this in the browser)
• The browser SDK uses your publishable key (safe to expose)
• Always use test mode during development
• Set the apiVersion to ensure consistent API behavior

Try It

1. Create Stripe account:

   • Go to stripe.com and sign up
   • Navigate to Developers → API keys
   • You should see Publishable key and Secret key in test mode

2. Add to environment:

   .env.local

   STRIPE_SECRET_KEY=sk_test_...
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

3. Restart dev server:

   pnpm dev

4. Verify no errors: The dev server should start without errors about missing Stripe configuration.

Commit

git add -A
git commit -m "feat(billing): add Stripe SDK configuration"

Done-When

• Stripe account created with test mode enabled
• STRIPE_SECRET_KEY added to .env.local (starts with sk_test_)
• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY added to .env.local (starts with pk_test_)
• utils/stripe/config.ts exports initialized stripe client
• utils/stripe/client.ts exports getStripe function
• Dev server runs without Stripe-related errors

Solution

Step 1: Create Stripe Account

1. Visit stripe.com and sign up
2. Once in the dashboard, ensure you're in Test mode (toggle in the top right)
3. Navigate to Developers → API keys
4. Copy both keys:
   • Publishable key starts with pk_test_
   • Secret key starts with sk_test_

Step 2: Configure Environment

Add the keys to your .env.local:

# Existing Supabase vars
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGci...
 
# Add Stripe keys
STRIPE_SECRET_KEY=sk_test_abc123...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xyz789...

Step 3: Create Server Stripe Client

Update utils/stripe/config.ts:

import Stripe from "stripe";
 
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? "", {
  apiVersion: "2025-02-24.acacia",
  appInfo: {
    name: "Foragers Guild",
    version: "1.0.0",
  },
});

This creates a Stripe client configured for server-side use:

• apiVersion - Locks to a specific API version for stability
• appInfo - Identifies your app in Stripe's dashboard and logs

Step 4: Create Browser Stripe Loader

Update utils/stripe/client.ts:

import { loadStripe, Stripe } from "@stripe/stripe-js";
 
let stripePromise: Promise<Stripe | null>;
 
export const getStripe = () => {
  if (!stripePromise) {
    stripePromise = loadStripe(
      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY ?? ""
    );
  }
  return stripePromise;
};

This lazy-loads the Stripe.js library:

• Singleton pattern - Only loads once, reuses the same instance
• loadStripe - Async function from @stripe/stripe-js
• Publishable key - Safe to use in the browser

File Structure After This Lesson

utils/
├── supabase/
│   ├── client.ts       ← From Section 1
│   ├── server.ts       ← From Section 1
│   └── proxy.ts        ← From Section 1
└── stripe/
    ├── config.ts       ← New: server Stripe client
    └── client.ts       ← New: browser Stripe loader

Server vs Browser SDK

The server SDK handles sensitive operations. The browser SDK handles client-side redirects.

Test Mode vs Live Mode

Always develop with test keys. Switch to live keys only for production deployment.

Troubleshooting

"Invalid API key" error:

• Verify the secret key starts with sk_test_
• Check you copied the full key without extra spaces
• Ensure .env.local is at the project root

"Stripe is not defined" in browser:

• The browser SDK loads asynchronously
• Always await getStripe() before using
• Verify the publishable key is set

API version warnings:

• Different API versions have different response shapes
• Lock to a specific version to avoid breaking changes
• Update the version when you're ready to migrate