Introduction
Welcome to SaaSphere SaaSphere NextJS SaaS Boilerplate
SaaSphere is a SaaSphere NextJS SaaS Boilerplate that provides a solid foundation for building your next SaaS project. It comes with a variety of features out of the box, including authentication, user management, subscription management, and more. This documentation page will guide you through setting up and customizing the boilerplate to fit your needs.
Sign up for SaaSphere
SaaSphere SaaSphere NextJS SaaS Boilerplate will save you hundreds of dev setup hours, allowing you to focus on your business goals.
Get started
After purchasing SaaSphere, you will get access to a tab in your dashboard called Repo access. Here you will be able to link your GitHub account to the SaaSphere repository. This will allow you to clone the repository and start building your SaaS.
Step 1: Get access to SaaSphere as a collaborator by entering your Github username in the input field on the Repo access page.
Step 2: Go to Github, fork the repository from the SaaSphere boilerplate repo and clone it to your local machine.
Step 3: Install dependencies
npm installStep 4: Start the development server
npm run devStep 5: Setup your environment variables
Environment variables
SaaSphere is built upon a multitude of environments, each serving a different purpose. These have been hand picked with scalability in mind to ensure your business can grow.
To fully setup SaaSphere you will need to create a .env file in the root of the project. This file should contain the following variables. Follow this page for a step by step guide on how to setup each of these variables.
# .env fileNEXT_PUBLIC_APP_URL=AUTH_TRUST_HOST=NEXTAUTH_URL=#Authentication and database setupAUTH_DRIZZLE_URL=AUTH_SECRET=GITHUB_CLIENT_ID=GITHUB_CLIENT_SECRET=GOOGLE_CLIENT_ID=GOOGLE_CLIENT_SECRET=#File management setup using AWS S3AWS_ACCESS_KEY_ID=AWS_SECRET_ACCESS_KEY=AWS_REGION=AWS_BUCKET_NAME=#Email setup using ResendRESEND_API_KEY=RESEND_FROM_EMAIL=#Payment setup using StripeNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=STRIPE_SECRET_KEY=STRIPE_WEBHOOK_SECRET=//Stripe subscription prices, these needed based on what payment plan/model you choose.NEXT_PUBLIC_STRIPE_SUB_ONE=NEXT_PUBLIC_STRIPE_SUB_TWO=NEXT_PUBLIC_STRIPE_SUB_THREE=NEXT_PUBLIC_STRIPE_ONE_TIME_ONE=NEXT_PUBLIC_STRIPE_ONE_TIME_TWO=#Optional blog and form environment variables, if you do not require a blog or form integration you can leave these blank and remove the relevant frontend code.NEXT_PUBLIC_FORM_URL=NEXT_PUBLIC_SANITY_PROJECT_ID=NEXT_PUBLIC_SANITY_DATASET=
Core ENVs
These are the core environment variables that are required for most functions within the app. Add the following ENVs and and put the values as the base url of your app, for local, this will be http://localhost:3000, for production deployments, this will be the root domain of your app. For example, SaaSphere's would be https://saasphere.dev
Why are these repeated?
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:3000
Authentication and database ENVs setup
SaaSphere SaaSphere NextJS SaaS Boilerplate uses Postgres for performance and scalability.
- Sign up to any Postgres provider. copy and paste the connection string into AUTH_DRIZZLE_URL
- Generate an auth secret and add it to AUTH_SECRET. This can be any string. You can run the following command to automatically generate a secure key.
- Run "npx drizzle-kit generate" inside the console, then run "npx drizzle-kit push" to push the schemas to your newly created database.
- Add your providers
npx auth secret
Neon Database
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:300056#Authentication and database setup7AUTH_DRIZZLE_URL=postgresql://random-user:pass123456@ep-forest-hill-b3x7fg7x-pooler.eu-west-2.aws.neon.tech/random-database?sslmode=require8AUTH_SECRET=r4nd0m_super_s3cr3t_k3y9GITHUB_CLIENT_ID=Ty97pkWrmhXDF8yhfho910GITHUB_CLIENT_SECRET=1d9824a7e85a8742e29c6cd09e67a103efb8f4c311GOOGLE_CLIENT_ID=8064532994112-hqe68lazp87n97kjwo12etpj10p5mp53.apps.googleusercontent.com12GOOGLE_CLIENT_SECRET=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
For a full list of setup steps for available provider, visit this link
Google setup
If you require Google sign in with your system, follow these steps
For official documentation on Google OAuth setup, visit this guide
Google for "google api console" and click "Google Cloud console", find create a new project in the navbar dropdown, name the project whatever you desire, press create, select your newly created project, search for "APIs & Services" in the search bar, click "OAuth consent screen" on the sidebar, check external, press create, fill in name, press save and continue, press save and continue, press save and continue, press "Credentials" on the left, press "Create Credentials", select OAuth client ID, select web application, name it, add "Authorised JavaScript origins" which is the base URL of your app, add "Authorised redirect URIs" to the format shown in image.
Press create, copy client id and secret on the right hand side of the page to the variables GOOGLE_CLIENT_ID=, GOOGLE_CLIENT_SECRET=. Ensure the providers you have provided keys for are enabled and that the UI is displaying then in social.tsx
Github setup
If you require Github sign in with your system, follow the documentation on guide linked below. After this, paste the client id and secret into the variables GITHUB_CLIENT_ID= and GITHUB_CLIENT_SECRET=
File management ENVs setup
SaaSphere SaaSphere NextJS SaaS Boilerplate uses AWS S3 for file management. This is an extremely scalable, cheap and reliable service that is used by many large companies.
Google for AWS S3 create an account, create a new S3 bucket, In Object Ownership, select "ACLs enabled" and "Bucket owner prefered" In Block Public Access settings for this bucket, uncheck "Block all public access" and check acknowledgement box, press create bucket. Click into your new bucket, go to the permissions tab, scroll down to bucket policy and select edit, then paste the following text inside. This will allow public access to the bucket.
Replace the resource
1{2"Version": "2012-10-17",3"Statement": [4{5"Sid": "PublicReadGetObject",6"Effect": "Allow",7"Principal": "*",8"Action": "s3:GetObject",9"Resource": "arn:aws:s3:::saasphere/*"10}11]12}
Set AWS_REGION= AWS_BUCKET_NAME= ENVs to your buckets region and buckets name. These can be found on the S3 homepage as shown below.
Click the top right dropdown and select security credentials, create a new access key copy and paste the resulting keys as AWS_ACCESS_KEY_ID= and AWS_SECRET_ACCESS_KEY=. Your ENV file should now look something like this.
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:300056#Authentication and database setup7AUTH_DRIZZLE_URL=postgresql://random-user:pass123456@ep-forest-hill-b3x7fg7x-pooler.eu-west-2.aws.neon.tech/random-database?sslmode=require8AUTH_SECRET=r4nd0m_super_s3cr3t_k3y9GITHUB_CLIENT_ID=Ty97pkWrmhXDF8yhfho910GITHUB_CLIENT_SECRET=1d9824a7e85a8742e29c6cd09e67a103efb8f4c311GOOGLE_CLIENT_ID=8064532994112-hqe68lazp87n97kjwo12etpj10p5mp53.apps.googleusercontent.com12GOOGLE_CLIENT_SECRET=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1314#File management setup using AWS S315AWS_ACCESS_KEY_ID=AKIAZPQRWSXTCHGUVOPN16AWS_SECRET_ACCESS_KEY=f+ND6zJhXOp8r2kxEHKd6V3+4qHqTkJvWyzr18TY17AWS_REGION=us-west-118AWS_BUCKET_NAME=random-saas-project-bucket
Resend email management setup
SaaSphere SaaSphere NextJS SaaS Boilerplate uses Resend for email management. This is an extremely scalable, cheap and reliable service that is used by many large companies. This service is used to send emails for password resets, email verification, etc.
Signup at https://resend.com then generate a secret token at https://resend.com Ensure you have a verified domain in your Resend account for production deployments to allow sending emails to users, if this isn't done, only the registered accounts email will be able to send and receive emails by using the email [email protected]. Follow the steps on resend to add a domain to your DNS records for production deployments.
Why do I need a verified domain?
Copy and paste the API key from Resend into the variables RESEND_API_KEY=, and RESEND_FROM_EMAIL=, if you have not verified a domain yet, you can use [email protected], but bare in mind this will only be able to send emails to the accounts registered email. Your ENV file should now look something like this.
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:300056#Authentication and database setup7AUTH_DRIZZLE_URL=postgresql://random-user:pass123456@ep-forest-hill-b3x7fg7x-pooler.eu-west-2.aws.neon.tech/random-database?sslmode=require8AUTH_SECRET=r4nd0m_super_s3cr3t_k3y9GITHUB_CLIENT_ID=Ty97pkWrmhXDF8yhfho910GITHUB_CLIENT_SECRET=1d9824a7e85a8742e29c6cd09e67a103efb8f4c311GOOGLE_CLIENT_ID=8064532994112-hqe68lazp87n97kjwo12etpj10p5mp53.apps.googleusercontent.com12GOOGLE_CLIENT_SECRET=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1314#File management setup using AWS S315AWS_ACCESS_KEY_ID=AKIAZPQRWSXTCHGUVOPN16AWS_SECRET_ACCESS_KEY=f+ND6zJhXOp8r2kxEHKd6V3+4qHqTkJvWyzr18TY17AWS_REGION=us-west-118AWS_BUCKET_NAME=random-saas-project-bucket1920#Email setup using Resend21RESEND_API_KEY=re_9DLWqvYT_A2pjFX8NsxpqeUbJV3oY8tLm22RESEND_FROM_EMAIL=support@random-saas-project.com23//use [email protected] if you have not verified a domain on Resend
Payment/billing ENVs setup
SaaSphere SaaSphere NextJS SaaS Boilerplate uses Stripe for payment management. This is used to manage subscriptions, one time payments and more. Follow the below steps to setup Stripe.
Stripe environments
Go to https://dashboard.stripe.com and register an account, setup your payment details. Copy secret key from the stripe dashboard homepage and pase into STRIPE_SECRET_KEY env. Then add NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY as the publishable key code. . You will be able to test payments with test keys using card details 424242424242 with any date in the future. see Stripe testing documentation for more details.
Setting up product prices
Search the search bar for product catalog in the Stripe dashboard, create a new product, and save it. Add all the necessary prices, ensuring you select the appropriate options for either one-time payments or subscriptions. Once the prices are set, locate and copy the corresponding price IDs into the appropriate slots in your environment file.
Note this will have to be done for both production and development prices by using the Test Mode toggle on the top right of the Stripe dashboard.
NEXT_PUBLIC_STRIPE_SUB_ONE=NEXT_PUBLIC_STRIPE_SUB_TWO=NEXT_PUBLIC_STRIPE_SUB_THREE=NEXT_PUBLIC_STRIPE_ONE_TIME_ONE=NEXT_PUBLIC_STRIPE_ONE_TIME_TWO=
If you need to add additional payment options, update the plans.ts file. For one-time payments, paste the price IDs into the one-time payment ENV fields; for subscriptions, paste them into the subscription ENV fields. By default, the dashboard is configured for subscription payment types. To ensure one-time payments are displayed correctly, follow these steps to adjust the components from subscription to one-time models: In app/(public)/page.tsx, replace the word "subscription" with "one-time" . In app/(protected)/dashboard/teams/[team]/billing/page.tsx, update the wording from "subscription" to "one-time" in places of the image shown below.
Setting up Stripe webhook
Production
Stripe webhooks are used to notify your app of events that happen in your Stripe account, such as payments being processed or subscriptions being created. To set up a webhook, follow these steps:
On stripe dashboard search for webhooks, create webhook. Add the following endpoint to your production webhook url.
- payment_intent.succeeded
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.payment_succeeded
- invoice.payment_failed
- checkout.session.completed
Press continue and then add your public path to the stripe api route, e.g for me https://saasphere.dev/api/webhooks/stripe. Copy this secret into your deployed STRIPE_WEBHOOK_SECRET
Development/local
To test Stripe payments locally, you'll need to install the Stripe CLI. Use the command brew install stripe/stripe-cli/stripe to install it. After that, run stripe login to log in to your account. Once logged in, start the webhook listener by running stripe listen --forward-to http://localhost:3000/api/webhooks/stripe. Copy the webhook secret generated and paste it into the STRIPE_WEBHOOK_SECRET environment variable.
Your ENV file should now look something like this.
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:300056#Authentication and database setup7AUTH_DRIZZLE_URL=postgresql://random-user:pass123456@ep-forest-hill-b3x7fg7x-pooler.eu-west-2.aws.neon.tech/random-database?sslmode=require8AUTH_SECRET=r4nd0m_super_s3cr3t_k3y9GITHUB_CLIENT_ID=Ty97pkWrmhXDF8yhfho910GITHUB_CLIENT_SECRET=1d9824a7e85a8742e29c6cd09e67a103efb8f4c311GOOGLE_CLIENT_ID=8064532994112-hqe68lazp87n97kjwo12etpj10p5mp53.apps.googleusercontent.com12GOOGLE_CLIENT_SECRET=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1314#File management setup using AWS S315AWS_ACCESS_KEY_ID=AKIAZPQRWSXTCHGUVOPN16AWS_SECRET_ACCESS_KEY=f+ND6zJhXOp8r2kxEHKd6V3+4qHqTkJvWyzr18TY17AWS_REGION=us-west-118AWS_BUCKET_NAME=random-saas-project-bucket1920#Email setup using Resend21RESEND_API_KEY=re_9DLWqvYT_A2pjFX8NsxpqeUbJV3oY8tLm22RESEND_FROM_EMAIL=support@random-saas-project.com232425#Payment setup using Stripe26NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51XyewLGm4K65Sy961ocIzBSHb9ZvGxXuQOVTG9w1a5fPwjwz8CYUivOBWlmhHm8fQXuDQSxm43387o9ZUSDZ7w000z7ABCDefg27STRIPE_SECRET_KEY=sk_test_51XyewLGm4K65Sy9dqztp7vfdXgrBHgH2KCXA65dx5rgXg0NKZPt3CcbBytevaWDBCZP5m1tXzWfQuoKJBiNtKY100l7X9lLxyz28STRIPE_WEBHOOK_SECRET=whsec_8aa9460e4eac9b5bfa36a90b858a55788396b2b61c947835d6461b11e9f8727e2930// Stripe subscription prices, these needed based on what payment plan/model you choose.31NEXT_PUBLIC_STRIPE_SUB_ONE=price_1XzFu7LGm4K65Sy9rxN4h1Co32NEXT_PUBLIC_STRIPE_SUB_TWO=price_1XzFuoLGm4K65Sy9HVFqJYAR33NEXT_PUBLIC_STRIPE_SUB_THREE=price_1XzFv7LGm4K65Sy9tzfJaVBB34// NEXT_PUBLIC_STRIPE_ONE_TIME_ONE=price_1Q7LvlLGm4K65Sy9lKYsCFDS35// NEXT_PUBLIC_STRIPE_ONE_TIME_TWO=price_1Q7LwRLGm4K65Sy9SrPT6V43
Contact form ENV setup
SaaSphere SaaSphere NextJS SaaS Boilerplate uses Formbold for contact form management. This is an extremely scalable, cheap and reliable service that is used by many large companies.
Formbold will connect to the landing pages contact form to forward you emails. Go to https://formbold.com , create an account, create a form, go to the integration tab and paste the code into NEXT_PUBLIC_FORM_URL,
Your ENV file should now look something like this.
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:300056#Authentication and database setup7AUTH_DRIZZLE_URL=postgresql://random-user:pass123456@ep-forest-hill-b3x7fg7x-pooler.eu-west-2.aws.neon.tech/random-database?sslmode=require8AUTH_SECRET=r4nd0m_super_s3cr3t_k3y9GITHUB_CLIENT_ID=Ty97pkWrmhXDF8yhfho910GITHUB_CLIENT_SECRET=1d9824a7e85a8742e29c6cd09e67a103efb8f4c311GOOGLE_CLIENT_ID=8064532994112-hqe68lazp87n97kjwo12etpj10p5mp53.apps.googleusercontent.com12GOOGLE_CLIENT_SECRET=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1314#File management setup using AWS S315AWS_ACCESS_KEY_ID=AKIAZPQRWSXTCHGUVOPN16AWS_SECRET_ACCESS_KEY=f+ND6zJhXOp8r2kxEHKd6V3+4qHqTkJvWyzr18TY17AWS_REGION=us-west-118AWS_BUCKET_NAME=random-saas-project-bucket1920#Email setup using Resend21RESEND_API_KEY=re_9DLWqvYT_A2pjFX8NsxpqeUbJV3oY8tLm22RESEND_FROM_EMAIL=support@random-saas-project.com232425#Payment setup using Stripe26NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51XyewLGm4K65Sy961ocIzBSHb9ZvGxXuQOVTG9w1a5fPwjwz8CYUivOBWlmhHm8fQXuDQSxm43387o9ZUSDZ7w000z7ABCDefg27STRIPE_SECRET_KEY=sk_test_51XyewLGm4K65Sy9dqztp7vfdXgrBHgH2KCXA65dx5rgXg0NKZPt3CcbBytevaWDBCZP5m1tXzWfQuoKJBiNtKY100l7X9lLxyz28STRIPE_WEBHOOK_SECRET=whsec_8aa9460e4eac9b5bfa36a90b858a55788396b2b61c947835d6461b11e9f8727e2930// Stripe subscription prices, these needed based on what payment plan/model you choose.31NEXT_PUBLIC_STRIPE_SUB_ONE=price_1XzFu7LGm4K65Sy9rxN4h1Co32NEXT_PUBLIC_STRIPE_SUB_TWO=price_1XzFuoLGm4K65Sy9HVFqJYAR33NEXT_PUBLIC_STRIPE_SUB_THREE=price_1XzFv7LGm4K65Sy9tzfJaVBB34// NEXT_PUBLIC_STRIPE_ONE_TIME_ONE=price_1Q7LvlLGm4K65Sy9lKYsCFDS35// NEXT_PUBLIC_STRIPE_ONE_TIME_TWO=price_1Q7LwRLGm4K65Sy9SrPT6V433637#Optional blog and form environment variables, if you do not require a blog or form integration you can leave these blank and remove the relevant frontend code.38NEXT_PUBLIC_FORM_URL=https://formbold.com/s/fake-form
CMS blog ENV setup
SaaSphere SaaSphere NextJS SaaS Boilerplate uses Sanity for blog management. This is a headless CMS that is simple and easy to use.
Go to https://www.sanity.io , create an account, create a new project from scratch, copy and paste project ID into NEXT_PUBLIC_SANITY_PROJECT_ID. Go to the datasets tab and create a dataset, put this name into NEXT_PUBLIC_SANITY_DATASET, go to /studio on the boilerplate. follow the steps on the screen to verify CORS. You can now add posts through the CMS interface
To enable your blog to revalidate on new posts, add a secret key to your ENV called SANITY_REVALIDATE_SECRET. Then on Sanity, go to the api tab, create a new token, and paste this into the frontend code. Then go to webhooks tab and create a new webhooks to your frontend URL, e.g https://saasphere.dev/api/revalidate.
Your ENV file should now look something like this.
1# .env file2NEXT_PUBLIC_APP_URL=http://localhost:30003AUTH_TRUST_HOST=http://localhost:30004NEXTAUTH_URL=http://localhost:300056#Authentication and database setup7AUTH_DRIZZLE_URL=postgresql://random-user:pass123456@ep-forest-hill-b3x7fg7x-pooler.eu-west-2.aws.neon.tech/random-database?sslmode=require8AUTH_SECRET=r4nd0m_super_s3cr3t_k3y9GITHUB_CLIENT_ID=Ty97pkWrmhXDF8yhfho910GITHUB_CLIENT_SECRET=1d9824a7e85a8742e29c6cd09e67a103efb8f4c311GOOGLE_CLIENT_ID=8064532994112-hqe68lazp87n97kjwo12etpj10p5mp53.apps.googleusercontent.com12GOOGLE_CLIENT_SECRET=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1314#File management setup using AWS S315AWS_ACCESS_KEY_ID=AKIAZPQRWSXTCHGUVOPN16AWS_SECRET_ACCESS_KEY=f+ND6zJhXOp8r2kxEHKd6V3+4qHqTkJvWyzr18TY17AWS_REGION=us-west-118AWS_BUCKET_NAME=random-saas-project-bucket1920#Email setup using Resend21RESEND_API_KEY=re_9DLWqvYT_A2pjFX8NsxpqeUbJV3oY8tLm22RESEND_FROM_EMAIL=support@random-saas-project.com232425#Payment setup using Stripe26NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51XyewLGm4K65Sy961ocIzBSHb9ZvGxXuQOVTG9w1a5fPwjwz8CYUivOBWlmhHm8fQXuDQSxm43387o9ZUSDZ7w000z7ABCDefg27STRIPE_SECRET_KEY=sk_test_51XyewLGm4K65Sy9dqztp7vfdXgrBHgH2KCXA65dx5rgXg0NKZPt3CcbBytevaWDBCZP5m1tXzWfQuoKJBiNtKY100l7X9lLxyz28STRIPE_WEBHOOK_SECRET=whsec_8aa9460e4eac9b5bfa36a90b858a55788396b2b61c947835d6461b11e9f8727e2930// Stripe subscription prices, these needed based on what payment plan/model you choose.31NEXT_PUBLIC_STRIPE_SUB_ONE=price_1XzFu7LGm4K65Sy9rxN4h1Co32NEXT_PUBLIC_STRIPE_SUB_TWO=price_1XzFuoLGm4K65Sy9HVFqJYAR33NEXT_PUBLIC_STRIPE_SUB_THREE=price_1XzFv7LGm4K65Sy9tzfJaVBB34// NEXT_PUBLIC_STRIPE_ONE_TIME_ONE=price_1Q7LvlLGm4K65Sy9lKYsCFDS35// NEXT_PUBLIC_STRIPE_ONE_TIME_TWO=price_1Q7LwRLGm4K65Sy9SrPT6V433637#Optional blog and form environment variables, if you do not require a blog or form integration you can leave these blank and remove the relevant frontend code.38NEXT_PUBLIC_FORM_URL=https://formbold.com/s/fake-form39NEXT_PUBLIC_SANITY_PROJECT_ID="poja245"40NEXT_PUBLIC_SANITY_DATASET="production"41SANITY_REVALIDATE_SECRET="r4nd0m_s4n1ty_r3v4l1d4t3_s3cr3t"