Awesome
Next.js Billing App with Lemon Squeezy
This Next.js demo app can be used as a base for building subscription-based SaaS apps.
Just clone this repo and build your app alongside the ready-made auth and billing.
Using the following stack:
- Framework - Next.js 14
- Language - TypeScript
- Billing - Lemon Squeezy
- Auth (GitHub OAuth) - Auth.js v5
- ORM - Drizzle
- Styling - Tailwind CSS
- Components - Wedges
- Serverless Postgres - Neon
- Linting - ESLint
- Formatting - Prettier
This template uses the Next.js App Router. This includes support for enhanced layouts, colocation of components, tests, and styles, component-level data fetching, and more.
Compatbile with Vercel Edge Functions and serverless deployments.
Customer Portal vs Integrated Billing
Keep in mind that Lemon Squeezy comes with inbuilt Customer Portal that covers all the features from this app and more.
Nonetheless, should you seek a billing solution more closely integrated with your SaaS platform, this template serves as a foundation for creating a seamless, integrated SaaS billing system.
Prerequisites
1. Lemon Squeezy Account and Store
You need a Lemon Squeezy account and store. If you don't have one already, sign up at Lemon Squeezy.
2. Neon Account
This template uses Neon + Drizzle ORM for serverless Postgres, making it compatible with the Vercel Edge functions. If you don't have an account, you can sign up for free at Neon.
Getting Started
1. Clone the Repo
Start by cloning this repo to your local machine and navigating into the directory.
2. Install Dependencies
Then, install the project dependencies:
pnpm install
3. Set Environment Variables
Copy the .env.example
file to .env
:
cp .env.example .env
Then, fill in the environment variables:
LEMONSQUEEZY_API_KEY=
LEMONSQUEEZY_STORE_ID=
LEMONSQUEEZY_WEBHOOK_SECRET=
WEBHOOK_URL=
POSTGRES_URL=
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
AUTH_SECRET=
AUTH_URL=
NEXT_PUBLIC_APP_URL=
Lemon Squeezy
Once you have created an account and store on Lemon Squeezy, make sure you're in Test mode, then go to Settings > API and create a new API key. Copy the key and paste it into .env
file where it says LEMONSQUEEZY_API_KEY=
.
You will also need the store ID from Lemon Squeezy for LEMONSQUEEZY_STORE_ID
, which you can find in the list at Settings > Stores.
Finally, you will need to add a random webhook secret in LEMONSQUEEZY_WEBHOOK_SECRET
. A webhook secret is a security key that ensures data received from a webhook is genuine and unaltered, safeguarding against unauthorized access.
Webhook URL
Your local app will need to be able to receive webhook events, which means creating a web-accessible URL for your development project.
This is not available when running your site on its local server without some sort of tunnel.
An easy way to set one up is using a service like ngrok or an app like LocalCan.
Once you are provided a URL by these services, simply add that in your .env
file where it says WEBHOOK_URL=
.
Postgres URL
You can get the Postgres URL from your Neon account. For more information refer to the Neon documentation.
Auth
You will need to set up a GitHub OAuth app in order to obtain GITHUB_SECRET
and GITHUB_ID
to handle authentication.
Refer to the GitHub documentation for setting up GitHub OAuth.
Once you have set up the OAuth app, you will need to add the AUTH_GITHUB_SECRET
and AUTH_GITHUB_ID
to your .env
file.
Additionally, you need to add a random secret for AUTH_SECRET
in your .env
file. On Linux or macOS, you can generate a random secret using the following command:
openssl rand -hex 32
or go to https://generate-secret.now.sh/32 to generate a random secret.
Next, you need to provide the URL of your app in AUTH_URL
in format https://your-app-url.com/api/auth
. For local development, you can use http://localhost:3000/api/auth
.
Finally, you will need to add the URL of your app in NEXT_PUBLIC_APP_URL
. For example, http://localhost:3000
.
Open http://localhost:3000 with your browser to see the result.
4. Set Up the Database
Run the following command to set up the database:
pnpm db:push
With Drizzle ORM, you can access the database with Drizzle Studio. Run the following command to open Drizzle Studio:
pnpm db:studio
Go to https://local.drizzle.studio/ to access the database.
5. Run the Development Server
Start the development server:
pnpm dev
That's all, you're ready to go!
How to set up Webhooks
This is a required step.
For your app to receive data from Lemon Squeezy, you need to set up webhooks in your Lemon Squeezy store at Settings > Webhooks.
In the app we have provided an action (Setup webhook button) that demonstrates how you can create a webhook on Lemon Squeezy using the Lemon Squeezy SDK.
When you create a webhook, you should check at least these two events:
subscription_created
subscription_updated
This app demo only processes these two events, but they are enough to get a billing system in place. You could, for example, extend the app to handle successful payment events to list invoices in your billing system (by subscribing to subscription_payment_success
).
The webhook endpoint in your app is /api/webhook
, which means if you are manually setting up the webhook, you need to append /api/webook
to your webhook URL on Lemon Squeezy. For example, https://your-app-url.com/api/webhook
The server action for creating a webhook via SDK will do that automatically for you.
In the webhook form you need to add a signing secret. Add the same value you use in the form in the LEMONSQUEEZY_WEBHOOK_SECRET
environment variable.
Production
There are a few things to update in your code to go live.
You need to turn off the Test mode in your Lemon Squeezy store and add a new live mode API key. Add this API key as an environment variable in your live server, using the same name LEMONSQUEEZY_API_KEY
. Your store ID remains the same in both test and live mode, so add that to your server environment variables, as you did for your development site.
You also need to create a new webhook in your live store. Make sure you add the signing secret into the LEMONSQUEEZY_WEBHOOK_SECRET
variable on your server.