Next.js Subscription Payments Starter

The all-in-one starter kit for high-performance SaaS applications.

Features

• Secure user management and authentication with Supabase
• Powerful data access & management tooling on top of PostgreSQL with Supabase
• Integration with Stripe Checkout and the Stripe customer portal
• Automatic syncing of pricing plans and subscription statuses via Stripe webhooks

Demo

• https://subscription-payments.vercel.app/

Architecture

Step-by-step setup

When deploying this template, the sequence of steps is important. Follow the steps below in order to get up and running.

Initiate Deployment

Vercel Deploy Button

The Vercel Deployment will create a new repository with this template on your GitHub account and guide you through a new Supabase project creation. The Supabase Vercel Deploy Integration will set up the necessary Supabase environment variables and run the SQL migrations to set up the Database schema on your account. You can inspect the created tables in your project's Table editor.

Should the automatic setup fail, please create a Supabase account, and a new project if needed. In your project, navigate to the SQL editor and select the "Stripe Subscriptions" starter template from the Quick start section.

Configure Auth

Follow this guide to set up an OAuth app with GitHub and configure Supabase to use it as an auth provider.

In your Supabase project, navigate to auth > URL configuration and set your main production URL (e.g. https://your-deployment-url.vercel.app) as the site url.

Next, in your Vercel deployment settings, add a new Production environment variable called NEXT_PUBLIC_SITE_URL and set it to the same URL. Make sure to deselect preview and development environments to make sure that preview branches and local development work correctly.

[Optional] - Set up redirect wildcards for deploy previews (not needed if you installed via the Deploy Button)

If you've deployed this template via the "Deploy to Vercel" button above, you can skip this step. The Supabase Vercel Integration will have set redirect wildcards for you. You can check this by going to your Supabase auth settings and you should see a list of redirects under "Redirect URLs".

Otherwise, for auth redirects (email confirmations, magic links, OAuth providers) to work correctly in deploy previews, navigate to the auth settings and add the following wildcard URL to "Redirect URLs": https://*-username.vercel.app/**. You can read more about redirect wildcard patterns in the docs.

If you've deployed this template via the "Deploy to Vercel" button above, you can skip this step. The Supabase Vercel Integration will have run database migrations for you. You can check this by going to the Table Editor for your Supabase project, and confirming there are tables with seed data.

Otherwise, navigate to the SQL Editor, paste the contents of the Supabase schema.sql file, and click RUN to initialize the database.

[Maybe Optional] - Set up Supabase environment variables (not needed if you installed via the Deploy Button)

If you've deployed this template via the "Deploy to Vercel" button above, you can skip this step. The Supabase Vercel Integration will have set your environment variables for you. You can check this by going to your Vercel project settings, and clicking on 'Environment variables', there will be a list of environment variables with the Supabase icon displayed next to them.

Otherwise navigate to the API settings and paste them into the Vercel deployment interface. Copy project API keys and paste into the NEXT_PUBLIC_SUPABASE_ANON_KEY and SUPABASE_SERVICE_ROLE_KEY fields, and copy the project URL and paste to Vercel as NEXT_PUBLIC_SUPABASE_URL.

Congrats, this completes the Supabase setup, almost there!

Configure Stripe

Next, we'll need to configure Stripe to handle test payments. If you don't already have a Stripe account, create one now.

For the following steps, make sure you have the "Test Mode" toggle switched on.

Create a Webhook

We need to create a webhook in the Developers section of Stripe. Pictured in the architecture diagram above, this webhook is the piece that connects Stripe to your Vercel Serverless Functions.

1. Click the "Add Endpoint" button on the test Endpoints page.
2. Enter your production deployment URL followed by /api/webhooks for the endpoint URL. (e.g. https://your-deployment-url.vercel.app/api/webhooks)
3. Click Select events under the Select events to listen to heading.
4. Click Select all events in the Select events to send section.
5. Copy Signing secret as we'll need that in the next step (e.g whsec_xxx) (/!\ be careful no to copy the webook id we_xxxx).
6. In addition to the NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY and the STRIPE_SECRET_KEY we've set earlier during deployment, we need to add the webhook secret as STRIPE_WEBHOOK_SECRET env var.

Redeploy with new env vars

For the newly set environment variables to take effect and everything to work together correctly, we need to redeploy our app in Vercel. In your Vercel Dashboard, navigate to deployments, click the overflow menu button and select "Redeploy" (do NOT enable the "Use existing Build Cache" option). Once Vercel has rebuilt and redeployed your app, you're ready to set up your products and prices.

Create product and pricing information

Your application's webhook listens for product updates on Stripe and automatically propagates them to your Supabase database. So with your webhook listener running, you can now create your product and pricing information in the Stripe Dashboard.

Stripe Checkout currently supports pricing that bills a predefined amount at a specific interval. More complex plans (e.g., different pricing tiers or seats) are not yet supported.

For example, you can create business models with different pricing tiers, e.g.:

• Product 1: Hobby
  • Price 1: 10 USD per month
  • Price 2: 100 USD per year
• Product 2: Freelancer
  • Price 1: 20 USD per month
  • Price 2: 200 USD per year

Optionally, to speed up the setup, we have added a fixtures file to bootstrap test product and pricing data in your Stripe account. The Stripe CLI fixtures command executes a series of API requests defined in this JSON file. Simply run stripe fixtures fixtures/stripe-fixtures.json.

Important: Make sure that you've configured your Stripe webhook correctly and redeployed with all needed environment variables.

Configure the Stripe customer portal

1. Set your custom branding in the settings
2. Configure the Customer Portal settings
3. Toggle on "Allow customers to update their payment methods"
4. Toggle on "Allow customers to update subscriptions"
5. Toggle on "Allow customers to cancel subscriptions"
6. Add the products and prices that you want
7. Set up the required business information and links

That's it

I know, that was quite a lot to get through, but it's worth it. You're now ready to earn recurring revenue from your customers. 🥳

Develop locally

If you haven't already done so, clone your Github repository to your local machine.

Install dependencies

Ensure you have pnpm installed and run:

pnpm install

Next, use the Vercel CLI to link your project:

pnpm dlx vercel login
pnpm dlx vercel link

pnpm dlx runs a package from the registry, without installing it as a dependency. Alternatively, you can install these packages globally, and drop the pnpm dlx part.

If you don't intend to use a local Supabase instance for development and testing, you can use the Vercel CLI to download the development env vars:

pnpm dlx vercel env pull .env.local

Running this command will create a new .env.local file in your project folder. For security purposes, you will need to set the SUPABASE_SERVICE_ROLE_KEY manually from your Supabase dashboard (Settings > API). If you are not using a local Supabase instance, you should also change the --local flag to --remote in the supabase:generate-types script in package.json.

Local development with Supabase

It's highly recommended to use a local Supabase instance for development and testing. We have provided a set of custom commands for this in package.json.

First, you will need to install Docker. You should also copy or rename:

• .env.local.example -> .env.local
• .env.example -> .env

Next, run the following command to start a local Supabase instance and run the migrations to set up the database schema:

pnpm supabase:start

The terminal output will provide you with URLs to access the different services within the Supabase stack. The Supabase Studio is where you can make changes to your local database instance.

Copy the value for the service_role_key and paste it as the value for the SUPABASE_SERVICE_ROLE_KEY in your .env.local file.

You can print out these URLs at any time with the following command:

pnpm supabase:status

To link your local Supabase instance to your project, run the following command, navigate to the Supabase project you created above, and enter your database password.

pnpm supabase:link

If you need to reset your database password, head over to your database settings and click "Reset database password", and this time copy it across to a password manager! 😄

🚧 Warning: This links our Local Development instance to the project we are using for production. Currently, it only has test records, but once it has customer data, we recommend using Branching or manually creating a separate preview or staging environment, to ensure your customer's data is not used locally, and schema changes/migrations can be thoroughly tested before shipping to production.

Once you've linked your project, you can pull down any schema changes you made in your remote database with:

pnpm supabase:pull

You can seed your local database with any data you added in your remote database with:

pnpm supabase:generate-seed
pnpm supabase:reset

🚧 Warning: this is seeding data from the production database. Currently, this only contains test data, but we recommend using Branching or manually setting up a preview or staging environment once this contains real customer data.

You can make changes to the database schema in your local Supabase Studio and run the following command to generate TypeScript types to match your schema:

pnpm supabase:generate-types
npx supabase gen types typescript --project-id ${PROJECT_ID} --schema public > types_db.ts

You can also automatically generate a migration file with all the changes you've made to your local database schema with the following command:

pnpm supabase:generate-migration

And push those changes to your remote database with:

pnpm supabase:push

Remember to test your changes thoroughly in your local and staging or preview environments before deploying them to production!

Database user setup

Follow the steps in fraction 6 in the docs page.

1.In your [Supabase] go to [Database] 2.Go to [Functions] on the left panel 3.Click [Create new function] 4.Name the function handle_new_user 5.Paste below code

begin
  insert into public.users (id, full_name, avatar_url, role)
  values (new.id, new.raw_user_meta_data->>'full_name', new.raw_user_meta_data->>'avatar_url', 'user');
  return new;
end;

6.Hit [Confirm]

Now, everytime a new user logs in, a new record will be stores in table users.

Use the Stripe CLI to test webhooks

Use the Stripe CLI to login to your Stripe account:

pnpm stripe:login

This will print a URL to navigate to in your browser and provide access to your Stripe account.

Next, start local webhook forwarding:

pnpm stripe:listen

Running this Stripe command will print a webhook secret (such as, whsec_***) to the console. Set STRIPE_WEBHOOK_SECRET to this value in your .env.local file. If you haven't already, you should also set NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY and STRIPE_SECRET_KEY in your .env.local file using the test mode(!) keys from your Stripe dashboard.

Use ngrok to test webhooks (easier)

1. Install ngrok - follow this tutorial
2. Go to folder where ngrok is downloaded/extracted & run ./ngrok http http://localhost:3000
3. Copy the address that ngrok shows in terminal
4. Go to Stripe dashboard, Developer, Add webhook and paste:

example https://e714-79-106-126-185.ngrok-free.app/api/webhooks 5. Get the webhook secret (reveal secret) from Stripe and put it in .env.local

Run the Next.js client

In a separate terminal, run the following command to start the development server:

pnpm dev

Note that webhook forwarding and the development server must be running concurrently in two separate terminals for the application to work correctly.

Finally, navigate to http://localhost:3000 in your browser to see the application rendered.

Going live

Archive testing products

Archive all test mode Stripe products before going live. Before creating your live mode products, make sure to follow the steps below to set up your live mode env vars and webhooks.

Configure production environment variables

To run the project in live mode and process payments with Stripe, switch Stripe from "test mode" to "production mode." Your Stripe API keys will be different in production mode, and you will have to create a separate production mode webhook. Copy these values and paste them into Vercel, replacing the test mode values.

Redeploy

Afterward, you will need to rebuild your production deployment for the changes to take effect. Within your project Dashboard, navigate to the "Deployments" tab, select the most recent deployment, click the overflow menu button (next to the "Visit" button) and select "Redeploy" (do NOT enable the "Use existing Build Cache" option).

To verify you are running in production mode, test checking out with the Stripe test card. The test card should not work.

Generate a privacy policy for a fictional company, "ShipFast", that respects user privacy regarding information collected across its website and other sites it owns. The policy should include the following elements:

Information Collection: Explain the conditions under which personal information is requested, emphasizing fair and lawful collection, user knowledge, and consent. Include an example of a signup method, such as using a Google account, and specify what data is collected (e.g., username and public profile picture).

Data Retention and Protection: Describe how long the information is retained and the measures taken to protect it from loss, theft, unauthorized access, disclosure, copying, use, or modification.

Data Sharing: State that personal information is not shared publicly or with third parties except when legally required.

Compliance: Clarify that ShipFast acts as a data controller and processor according to relevant data protection laws, including the EU GDPR.

External Links: Note that the website may link to external sites not operated by ShipFast, and ShipFast is not responsible for their privacy policies.

User Rights: Inform users they can refuse to provide personal information, with the understanding that it might limit the services available to them.

Acceptance and Contact Information: Mention that continued use of the website implies acceptance of the privacy practices, and provide a way for users to contact ShipFast with questions about data handling and privacy.

Effective Date: Include an effective date for the policy.

The resulting privacy policy should be clear, concise, and in plain language.

Generate Privacy Policy with ChatGPT Prompt

generate a privacy policy like this one and avoid plagiarim:

Name of my website is ShipQuick so replace ShipFast with Shipquick everywhere.

Policy:

Your privacy is important to us. It is ShipFast's policy to respect your privacy regarding any information we may collect from you across our website, and other sites we own and operate.

We only ask for personal information when we truly need it to provide a service to you. We collect it by fair and lawful means, with your knowledge and consent. We also let you know why we're collecting it and how it will be used.

You can sign up with your Google account so your ShipFast's account username will be prefilled with your name and your public profile picture.

We only retain collected information for as long as necessary to provide you with your requested service. What data we store, we'll protect within commercially acceptable means to prevent loss and theft, as well as unauthorised access, disclosure, copying, use or modification.

We don't share any personally identifying information publicly or with third-parties, except when required to by law.

We act in the capacity of a data controller and a data processor with regard to the personal data processed through ShipFast and the services in terms of the applicable data protection laws, including the EU General Data Protection Regulation (GDPR).

Our website may link to external sites that are not operated by us. Please be aware that we have no control over the content and practices of these sites, and cannot accept responsibility or liability for their respective privacy policies.

You are free to refuse our request for your personal information, with the understanding that we may be unable to provide you with some of your desired services.

Your continued use of our website will be regarded as acceptance of our practices around privacy and personal information. If you have any questions about how we handle user data and personal information, feel free to contact us.

This policy is effective as of 26 July 2023.