Skip to main content
More in Learn

Next.js SaaS Boilerplate

PhotoFinder is a full-featured SaaS boilerplate built with Next.js and Crystallize, leveraging Crystallize new Subscription API and powerful rich content management (CMS) functionality that we offer out-of-the-box. You can check out this boilerplate live demo here.

Next.js SaaS Boilerplate

TypeScript + Next.js + Service API + Vercel

PhotoFinder is a full-featured SaaS boilerplate built with Next.js and TypeScript. It includes the landing page, about page, features page, and its own blog, powered by Crystallize CMS. It also includes its own design system built with Stitches and Storybook.

The boilerplate also includes magic email authentication and the signup flow with Stripe payment. Furthermore, this is our first boilerplate that introduces our integration with Two.inc (previously Tillit.ai), a B2B payment solution.

Because of the new Subscription API and the integration with Two.inc, this boilerplate needs to have its own Service API built on top of the great foundation of our Service API boilerplate.

Getting Started

You can use Crystallize CLI to bootstrap your next SaaS unicorn.

npx @crystallize/cli <your-project-name>

Running this command will allow you to add in the following:

  • The preferred boilerplate, which will be “Next.js - Subscription Commerce” in this case.
  • The tenant: you can either enter your own tenant or go with the demo tenant to test everything out.

Running the Project

Running the project in development is very straightforward. Running the following command will start up the development server:

cd website && yarn dev

or

cd website && npm run dev

Application Structure

This section provides you with a better understanding of the application structure.

saas-boilerplate
|
|-- service-api
|   |-- lib
|   |-- pages/api
|   |   |-- crystallize
|   |   |-- user
|   |   |-- webhooks
|   |-- src
|   |   |-- graphql-server
|   |   |-- lib
|   |   |-- services
|   |   |-- webhooks
|
|-- website
|   |-- src
|   |   |-- components
|   |   |-- config
|   |   |-- contexts
|   |   |-- crystallize
|   |   |-- design-system
|   |   |-- hooks
|   |   |-- pages
|   |   |-- service-api
|   |   |-- stories
|   |   |-- types
|   |   |-- utils
|   |   |-- clients.ts

Change Theme / UI Components

Crystallize SaaS Boilerplate utilizes Stitches.dev to build its design system. It already includes some common basic components like Button, TextField, Avatar, or even Typography for texts and headings.

You can find the design system at website/design-system

saas-boilerplate
|
|-- website
|   |-- src
|   |   |-- design-system
|   |   |   |-- components
|   |   |   |-- icons
|   |   |   |-- theme

You can find the design tokens like colors, spacings, font sizes in the theme folder. All the components are in the components folder with Storybook setup for easy development and documentation.

Environment Variables

Here are the environment variables you need on the front end:

NEXT_PUBLIC_CRYSTALLIZE_TENANT_IDENTIFIER=<your-tenant>
NEXT_PUBLIC_SERVICE_API_URL=<your-service-api>

During local development, you can set the

NEXT_PUBLIC_SERVICE_API_URL 

to [localhost:3001](<http://localhost:3001>) or whichever port you decide to run the service API.

As for the back end:

CRYSTALLIZE_TENANT_IDENTIFIER=<your-tenant>
JWT_SECRET=some-secret-jwt-key-goes-here
EMAIL_FROM=
CRYSTALLIZE_ACCESS_TOKEN_ID=
CRYSTALLIZE_ACCESS_TOKEN_SECRET=
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
SENDGRID_API_KEY=
SERVICE_CALLBACK_HOST=
TILLIT_API_KEY=

Vercel

For this guide, we will use Vercel CLI to get your project up and running right away.

Deploying the Back End

# at root
cd service-api

vercel

Following the prompt, you will be able to set up a new project and deploy. It may not work the first time as you haven’t set up the environment variables yet. Navigate to Vercel Dashboard and enter your secrets and try running vercel again to deploy.

To deploy the production environment, run

vercel --prod

You need to set up a custom domain so the front end and Service API can communicate with each other via same site cookies. I suggest something like api.mydomain.com.

Deploying the Front End

# at root
cd website

vercel

Similarly, it will fail the first time you deploy as you haven’t set up the environment variables. Navigate to Vercel Dashboard again and enter your secrets. This time, use the Service API URL you just deployed as the value of

NEXT_PUBLIC_SERVICE_API_URL=https://api.mydomain.com

From then on, you can deploy the service API or the website separately whenever you want. As the SaaS boilerplate is sort-of a monorepo (multiple projects — website and service API, within one repo), you can check out Vercel’s monorepo guide to set up CI/CD with GitHub as well.

Netlify

We can also use Netlify CLI to deploy your next SaaS project.

Deploying the Back End

# at root
cd service-api

netlify

Following the prompt, you will be able to set up a new project and deploy it. It may not work the first time as you haven’t set up the environment variables yet. Navigate to Netlify Dashboard and enter your secrets and try running netlify again to deploy.

To deploy the production environment, run

netlify --prod

You need to set up a custom domain so the front end and Service API can communicate with each other via same site cookies. I suggest something like api.mydomain.com.

Deploying the Front End

# at root
cd website

netlify

Similarly, it will fail the first time you deploy as you haven’t set up the environment variables. Navigate to Netlify Dashboard again and enter your secrets. This time, use the Service API URL you just deployed as the value of

NEXT_PUBLIC_SERVICE_API_URL=https://api.mydomain.com

From then on, you can deploy the service API or the website separately whenever you want. As the SaaS boilerplate is sort-of a monorepo (multiple projects — website and service API, within one repo), you can check out Netlify’s monorepo guide to set up CI/CD with GitHub as well.

People showing thumbs up

Need further assistance?

Ask the Crystallize team or other enthusiasts in our slack community.

Join our slack community