lmsqueezy/nextjs-billing

Follow these steps to get the project running locally:

1. Clone the repository and enter the directory.
2. Install dependencies using pnpm:

   pnpm install

3. Configure environment variables: Copy the example file:

   cp .env.example .env

   Fill in the required keys (see Environment Variables Reference).
4. Set up the database: Push the schema to your Postgres instance:

   pnpm db:push

5. Start the development server:

   pnpm dev

   The app will be available at http://localhost:3000.

When moving from development to production, perform the following steps:

1. Switch Lemon Squeezy Mode: Turn off Test mode in your Lemon Squeezy store.
2. Update API Key: Generate a new API key for Live mode and update LEMONSQUEEZY_API_KEY in your production environment.
3. Update Webhooks: Create a new webhook in your live store pointing to your production URL (e.g., https://your-production-app.com/api/webhook).
4. Update Webhook Secret: Ensure the new webhook's signing secret is reflected in your production LEMONSQUEEZY_WEBHOOK_SECRET environment variable.

Note: The LEMONSQUEEZY_STORE_ID remains the same for both test and live modes.

Webhooks are required for the app to process subscription changes.

Manual Setup

1. Go to Settings > Webhooks in your Lemon Squeezy store.
2. Set the webhook URL to your app's endpoint: https://your-app-url.com/api/webhook.
3. Select at least these two events:
   • subscription_created
   • subscription_updated
4. Add a signing secret in Lemon Squeezy and ensure the exact same value is set in your LEMONSQUEEZY_WEBHOOK_SECRET environment variable.

Automated Setup

The app includes a Setup webhook button (a server action) that uses the Lemon Squeezy SDK to create the webhook for you automatically, including the correct endpoint path.

This project uses Drizzle ORM with Neon Postgres.

To push your schema changes to the database:

pnpm db:push

To inspect your data using Drizzle Studio, run:

pnpm db:studio

This will open a local instance of Drizzle Studio at https://local.drizzle.studio/.

Use the configureLemonSqueezy function to initialize the Lemon Squeezy JS SDK and validate that all necessary environment variables are present. This function must be called during your application's setup phase to ensure the SDK is correctly configured before any billing operations occur.

Required Environment Variables

The following variables must be defined in your .env file:

• LEMONSQUEEZY_API_KEY: Your Lemon Squeezy API key.
• LEMONSQUEEZY_STORE_ID: Your Lemon Squeezy store identifier.
• LEMONSQUEEZY_WEBHOOK_SECRET: The secret used to validate incoming webhooks.

If any of these variables are missing, the function will throw an error listing the specific missing keys.

import { configureLemonSqueezy } from './src/config/lemonsqueezy';

// Call this during app initialization
configureLemonSqueezy();

The syncPlans action synchronizes product variants from your Lemon Squeezy store with your local plans database table.

Behavior:

1. It fetches all products and their variants from Lemon Squeezy.
2. It filters for variants where the category is subscription.
3. It skips draft variants or pending variants if multiple exist.
4. It calculates pricing (handling both usage-based and fixed pricing), intervals, and trial periods.
5. It performs an upsert (onConflictDoUpdate) into the plans table using variantId as the target.

This should be run whenever you add or modify subscription products in the Lemon Squeezy dashboard.

// Syncs Lemon Squeezy subscription variants to your local DB
const updatedPlans = await syncPlans();

Use formatDate to convert a date (string, number, Date object, or null/undefined) into a localized US English string with the format: Month Day, Year (e.g., Jan 01, 2024). If no valid date is provided, it returns an empty string.

import { formatDate } from "@/lib/utils";

const dateStr = formatDate(new Date()); // "Oct 24, 2023"
const empty = formatDate(null); // ""

Use isValidSubscription to determine if a Lemon Squeezy subscription status represents an active, usable subscription. A subscription is considered valid only if its status is not cancelled, expired, or unpaid.

import { isValidSubscription } from "@/lib/utils";

// status is derived from Subscription["data"]["attributes"]["status"]
const isActive = isValidSubscription("active"); // true
const isInvalid = isValidSubscription("cancelled"); // false

Call checkRequiredEnv to ensure the application has the necessary Lemon Squeezy credentials configured. This function throws an error if either LEMONSQUEEZY_API_KEY or LEMONSQUEEZY_STORE_ID is missing from process.env.

import { checkRequiredEnv } from "@/lib/utils";

// Call this during app initialization or in a server-side entry point
try {
  checkRequiredEnv();
} catch (error) {
  console.error(error.message);
}

The cn utility combines clsx and tailwind-merge. Use it to conditionally apply CSS classes and ensure that Tailwind class conflicts are resolved correctly (the last class passed wins).

import { cn } from "@/lib/utils";

// Resolves conflicts: 'p-4' is overridden by 'p-2'
const className = cn("p-4 text-red-500", "p-2"); // "p-2 text-red-500"

// Conditional classes
const dynamicClass = cn("base-class", isActive && "active-class");