Local Setup

Prerequisites

Before starting the setup, ensure you have the following accounts ready:

1. Supabase Account

   • Sign up or Sign in to your Supabase account.
   • Create a new project in Supabase, which will serve as the backend for the authentication, database, and storage.

2. Stripe/Lemonsqueezy Account

   • Sign up or Sign in to your Stripe/Lemonsqueezy account.
   • This is required for handling payments and billing.

3. Resend Account

   • Sign up or Sign in to Resend account.
   • This is required for handling email (Marketing and Transactional) functionality.

Steps for Local Setup

Clone the Repository

Clone the repository to your local machine using git:

git clone git@github.com:usesaaskit/nextjs-supabase-ai-template-v2.git

Navigate to the project directory:

cd nextjs-supabase-ai-template-v2

Install Dependencies

Install the required dependencies using npm (Node package manager):

npm install

Setup Supabase

You can use either a local or cloud Supabase environment to run the application locally. We recommend using the local Supabase environment during development.

Local (Optional)

To set up a local Supabase instance, you need to install Docker. You can install Docker by visiting this link.

Once Docker is installed, run the following command:

npm run supabase:start

This command will pull Supabase Docker images and run them as containers. Next, apply the migration and generate types:

npm run supabase:apply-migration

Navigate to the supabase directory in template:

cd supabase

Then generate the types:

npm run supabase:types

To get your local Supabase credentials, you can run the following command in the root folder. This will provide the anon key, secret key, API URL, Studio URL, and other configuration information.

npm run supabase:status

Go to the SQL section under Supabase Studio and run this command:

INSERT INTO storage.buckets
  (id, name, public)
VALUES
  ('avatars', 'avatars', true);

Cloud (Optional)

If you prefer to use the cloud version of Supabase, follow the cloud-specific instructions provided below:

First, you need to push the migration from your local environment to the cloud environment.

Install the Supabase CLI on your local machine.

Next, push the migration to the Supabase cloud environment using the following commands:

1. List your Supabase projects: This command will display the available Supabase projects linked to your account.

   supabase projects list

2. Link your local project to the Supabase cloud project: Replace $PROJECT_REF with the reference ID of the project you want to link to.

   supabase link --project-ref $PROJECT_REF

3. Push the database migration to the cloud: This command applies your local migrations to the Supabase cloud environment.

   supabase db push 

4. Go to the SQL section in Supabase Studio by visiting https://supabase.com/dashboard/project/_/sql/new, select your project, and then run this command:

   INSERT INTO storage.buckets
   (id, name, public)
   VALUES
   ('avatars', 'avatars', true);

Setup Application Configuration File

The app configuration is managed in src/app.config.ts. Update this file to fit your needs.

We support both Stripe and LemonSqueezy as payment providers. Be sure to update the settings based on the provider you're using.

Each option in the config file includes comments explaining what it does to help you understand how to set it up.

Setup Resend

Setup Domain

To set up a domain, go to the following link and click the "+ Add Domain" button.

Resend will guide you through the DNS registrar setup. Once the domain name is verified, you can proceed to set up the API Key.

Setup API Key

To set up an API Key, go to the following link and click the "+ Create API Key" button.

If you're also setting up an audience, grant full permissions; otherwise, you can grant only "Sending access" permission.

Setup Audience (Optional)

To set up an audience, go to the following link, where you will see one audience created by default.

This audience ID will need to be added to your environment variables.

Setup Webhook (Optional)

To set up a webhook, go to the following link and click the "+ Add Webhook" button.

For local environments, you can use ngrok to create a tunnel for localhost:3000. Add the webhook URL as follows: https://<ngrok-url>/api/webhook/resend

For events, the code is currently configured to accept only the contact.updated event.

Setup Stripe

You need Stripe CLI installed for local development. You can download it from stripe official documentation.

Create a Product

1. Log in to your Stripe Dashboard.
2. Navigate to Products in the left sidebar.
3. Click the + Add product button.
4. Fill in the product details (Name, Description, etc.) and click Save.
5. After saving, you’ll be redirected to the product page where you can add pricing information.

Create a Price

1. On the product page, click + Add price.
2. Select the pricing model (Recurring or One-time).
3. Set the price, billing interval (for subscriptions), and currency.
4. Click Save.

You can add multiple prices for different billing frequencies (e.g., monthly and yearly plans). Each price will have its own price_id.

Setup Stripe Webhooks

Webhooks allow Stripe to notify your app when certain events happen, like when a payment succeeds or a subscription is created.

Steps to Forward Webhooks Locally with Stripe CLI

1. Install the Stripe CLI if you haven't already.
2. Authenticate with your Stripe account:

stripe login

3. Start forwarding webhook events to your local server running at localhost:3000:

stripe listen --forward-to localhost:3000/api/webhook

4.Stripe CLI will provide you with a Webhook Secret (e.g., whsec_...). Use this secret in your application to verify webhook signatures.

This are the events that are being handled by webhook endpoint:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted

Setup LemonSqueezy

You need a LemonSqueezy account to manage products and subscriptions. You can sign up at lemonsqueezy.com.

Create a Product:

1. Log in to your LemonSqueezy Dashboard.
2. Navigate to Products from the sidebar.
3. Click the + New Product button.
4. Fill in the product details (Name, Description, Files, License Keys, etc.).
5. Under the Pricing section, define your price, currency, and subscription billing interval ( We only support ).
6. Click Save Product.

After saving, you can access the product’s checkout URL and other settings.

Create a Price

Pricing is part of the product setup in LemonSqueezy. When creating or editing a product:

1. Scroll to the Pricing section.
2. Choose Subscription.
3. Enter the price, billing frequency (for subscriptions), and currency.
4. Save the product to apply your pricing.

Each product will have a unique product_id and corresponding variant_id for handling different price options.

Setup LemonSqueezy Webhooks

Webhooks allow LemonSqueezy to notify your application about events like successful payments, subscription changes, and refunds.

1. Sign in to your LemonSqueezy Dashboard.
2. Go to Settings → API & Webhooks.
3. Under Webhooks, click + New Webhook.
4. Set the Webhook URL (for local development, this will be your ngrok URL, e.g., https://<ngrok-url>/api/webhook).
5. Choose the events you want to subscribe to, such as:

• subscription_created
• subscription_updated
• subscription_cancelled
• subscription_resumed
• subscription_expired

6. Click Save Webhook.

LemonSqueezy will send POST requests to your endpoint whenever these events occur.

Test Webhooks Locally

To test webhooks locally, use ngrok or a similar tunneling service to expose your local server.

Example:

ngrok http 3000

Configure env variables

Copy the .env.example file and rename it to .env.local:

  cp .env.example .env.local

Open the .env.local file and fill in the environment variables related to: Supabase, Stripe/Lemonsqueezy, Resend.

The environment variables will look something like this:

 
# Supabase
JWT_SECRET_KEY=
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_KEY=
 
# Resend
RESEND_FROM_DOMAIN=
RESEND_API_KEY=
RESEND_AUDIENCE_ID=
 
NEXT_PUBLIC_SITE_BASE_URL="http://localhost:3000"
BILLING_ENVIRONMENT=development
 
# Stripe ( Required if you choose stripe as payment provider )
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=
 
# Lemonsqueezy ( Required if you choose lemonsqueezy as payment provider)
LEMONSQUEEZY_WEBHOOK_SECRET=
LEMONSQUEEZY_API_KEY=
LEMONSQUEEZY_STORE_ID=
 
# Google
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=
 
# Github
GITHUB_OAUTH_CLIENT_ID=
GITHUB_OAUTH_CLIENT_SECRET=

Start the application

• Run the application in development mode:

  npm run dev

View your application

• Open your browser and navigate to:

http://localhost:3000

You should now see your application running locally. You're all set!