Paddle Next.js Starter Kit

To prevent unauthorized sellers, you must approve your Vercel deployment URL within the Paddle dashboard before checkouts will work.

1. Website Approval: Go to Paddle > Checkout > Website approval, enter your Vercel app URL, and click Submit for approval.
2. Default Payment Link: Go to Paddle > Checkout > Checkout settings, enter your Vercel app URL as the default payment link, and click Save.
3. Webhook Verification: Go to Paddle > Developer tools > Notifications and ensure the endpoint URL matches your Vercel domain (e.g., https://your-app.vercel.app/api/webhook).

You can deploy the project to Vercel by cloning the repository directly through the Vercel deployment button or by creating a new application manually.

During deployment, you must configure the following environment variables to connect your Paddle and Supabase accounts.

https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FPaddleHQ%2Fpaddle-nextjs-starter-kit&env=PADDLE_API_KEY,PADDLE_NOTIFICATION_WEBHOOK_SECRET,NEXT_PUBLIC_PADDLE_ENV,NEXT_PUBLIC_PADDLE_CLIENT_TOKEN&integration-ids=oac_VqOgBHqhEoFTPzGkPd7L0iH6&external-id=https%3A%2F%2Fgithub.com%2FPaddleHQ%2Fpaddle-nextjs-starter-kit%2Ftree%2Fmain

After deploying, you need to define your products and prices in Paddle and link them to the application.

1. Create Products in Paddle

Create products and prices in your Paddle dashboard. A common pattern is to create three products (one for each tier) with two prices each (e.g., 'monthly' and 'annual').

2. Update Local Constants

Copy your new Price IDs and update the constants in the following file: src/constants/pricing-tier.ts

3. Sync Changes

Commit and push your changes to the main branch to update the deployed application.

For deeper technical implementation and reference, use the following resources:

• Build and deploy Next.js app with Vercel and Supabase: A guide for integrating the stack used in this starter kit.
• Paddle API reference: The official documentation for all Paddle Billing API endpoints and methods.
• Sign up for Paddle Billing: Link to create a Paddle account to begin using the service.

Before setting up the starter kit, ensure your environment meets the following requirements:

Local Environment

• Node.js: Version > 20
• Package Manager: npm, Yarn, or pnpm

Required Accounts

• Vercel account (for deployment)
• Supabase account (for auth and database)
• Paddle Billing account (Sandbox account is recommended for testing)

Once configured, verify the integration by launching a checkout from your pricing page. If using a Paddle Sandbox account, use the following test card details:

The middleware in this project uses a config object with a matcher array to define which request paths should trigger the middleware execution. The default configuration is designed to run on all paths except for static assets, optimized images, the favicon, and common image file extensions (svg, png, jpg, jpeg, gif, webp). This prevents unnecessary session updates on static file requests.

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * Feel free to modify this pattern to include more paths.
     */
    '/((?!_next/static|_next/image|favicon.ico|.*\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
};

Use the signInWithGithub server action to initiate a GitHub OAuth flow. This action uses Supabase Auth to redirect the user to GitHub for authentication. The callback URL is hardcoded to https://paddle-billing.vercel.app/auth/callback. Note that this action performs a redirect internally.

// Call the action (it handles the redirect internally)
await signInWithGithub();

Use validateUserSession() to ensure a user is authenticated before performing sensitive server-side operations.

This function:

1. Initializes a Supabase client via createClient().
2. Attempts to retrieve the current session via supabase.auth.getSession().
3. Throws an error with the message 'You are not allowed to perform this action.' if no session is found.

If the function completes without throwing, the user is considered authenticated.

import { validateUserSession } from '@/utils/supabase/server';

export async function MyServerAction() {
  try {
    await validateUserSession();
    // Proceed with protected logic
  } catch (error) {
    // Handle unauthorized access
    console.error(error.message);
  }
}

Use getErrorMessage to retrieve a standardized error object. This is useful for populating UI error states when a Paddle operation fails.

It returns an object with the following structure:

• error: The string 'Something went wrong, please try again later'
• data: An empty array []
• hasMore: false
• totalRecords: 0

import { getErrorMessage } from '@/utils/paddle/data-helpers';

const errorState = getErrorMessage();
// Returns: { error: 'Something went wrong, please try again later', data: [], hasMore: false, totalRecords: 0 }