Quick Start

In this guide, you'll learn how to quickly setup a SaaS project using Nextacular's codebase.

Project Setup

1. Use Template and Clone Project

Visit Nextacular's Github repository (https://github.com/nextacular/nextacular) and click the "Use this template" button and complete the setup. After creating the template, clone the newly created project from the template into your local machine.

git clone https://github.com/<GITHUB_USERNAME>/<PROJECT_REPOSITORY>

2. Install Dependencies

Go to the root directory of your project and install the dependencies.

npm install

3. Setup Environment Variables

Make a copy of the .env.sample file as your local .env file. This is where we will store our environment variable values.

cp .env.sample .env

Open the .env file with your favorite text editor and update the minimum required environment variables.

Required Environment Variables

Copy the content for the environment variables below:

APP_URL = http://localhost:3000

# Database Configuration
DATABASE_URL = [POSTGRES_URL_HERE]

# Vercel API
NEXT_PUBLIC_VERCEL_IP_ADDRESS = 76.76.21.21
VERCEL_API_URL = https://api.vercel.com

We will need to provide values for the following environment variables:

1. DATABASE_URL

The following environment variables are optional:

1. NEXTAUTH_URL*

2. NEXTAUTH_SECRET*

3. SHADOW_DATABASE_URL* (You'll need this for Heroku Postgres DB)

To generate NEXTAUTH_SECRET:

openssl rand -base64 32

The DATABASE_URL and SHADOW_DATABASE_URL should come from your database provider.

* For optional environment variables, check the documentation here:

• NEXTAUTH_URL = https://next-auth.js.org/configuration/options#nextauth_url

• NEXTAUTH_SECRET = https://next-auth.js.org/configuration/options#nextauth_secret

• SHADOW_DATABASE_URL = https://www.prisma.io/docs/concepts/components/prisma-migrate/shadow-database

4. Generate Database Migrations

Before we actually run the application, let's generate the database migrations via Prisma migration command.

npx prisma migrate dev

5. Run Application

After the migration is done, we can now successfully run our application by executing the following command:

npm run dev

Congratulations on setting up the backbone of your SaaS application! 🎉

Local Development Common Issues

Despite trying our best to work on making Nextacular run on our local machines successfully, there will be instances where we will still encounter issues unusual for us.

The following list below is some of the most common development setup issues we encountered on our Discord server.

Feel free to share your workarounds and how you solved them on our Discord server.

Invalid URL

This may be a result of an invalid environment property file.

Things to note:

• Remove comments on the same line as the value

  • Example: APP_URL = http://localhost:3000 #https

• NEXTAUTH_URL might be needed.

  • NEXTAUTH_URL = $APP_URL

  • NOTE: Using $APP_URL will only work in local development, to make it work in production/live environments, you will have to use your actual APP_URL value.

Invalid Authentication (Next Auth Warning)

Another probable cause of an invalid environment property file.

Things to note:

• NEXTAUTH_URL in this case, is going to be required.

  • NEXTAUTH_URL = $APP_URL

  • NOTE: Using $APP_URL will only work in local development, to make it work in production/live environments, you will have to use your actual APP_URL value.

• NEXTAUTH_SECRET will be needed.

  • Generate a secret using openssl rand -base64 32 the command found in the .env.sample file.

Database Not Working

This was pretty common when using a database cloud provider that is not Heroku for most of our encounters.

Things to note:

• Make sure that the database connection string is correct.

• Special characters in environment variables should be escaped or converted.

• You can also enclose the database values in double-quotes.

• Depending on the type of database you selected, update the datasource db provider in schema.prisma file.