search

nemanjam / nextjs-prisma-boilerplate

Full stack boilerplate with Next.js, Prisma, Tailwind, TypeScript, Docker, Postgres, documentation, frontend and backend unit and integration tests with Jest, Cypress end-to-end tests, Github Actions CI/CD workflows, and production deployment with Traefik and Docker.
https://nextjs-prisma-boilerplate.arm1.nemanjamitic.com
MIT License
640 stars 85 forks source link
authentication boilerplate cicd cypress docker github-actions jest nextjs postgresql prisma react react-hook-form react-query react-testing-library starter-project tailwindcss traefik typescript

readme

Next.js Prisma Boilerplate

tests docker build deploy Docker Image Size (tag) GitHub

This is full stack boilerplate built around latest Next.js stack. It is composed of the best practices described in official docs combined with my decisions derived from my own experience and knowledge that I have gathered from working with other people.

Don't spend next 3 months making architectural decisions, choosing libraries, setting up dev and prod environments and CI/CD pipelines, writing boilerplate code, instead install this boilerplate in 15 minutes and start working on your features today.

Demo

Live production demo:

If the app is vandalized just use Reseed link on the right side of the footer to reseed the database.

Gitpod development playground:

You need Gitpod account, and maybe Postgres database url if my demo database is vandalized. You can create one on elephantsql.com, see Gitpod Environment section for details.

Screenshots

Desktop:

https://user-images.githubusercontent.com/9990165/177367837-a2692e5d-b694-454e-806d-21e806465836.mp4

Mobile:

Usage

Features

Tech stack:

React 18.2.0, Next.js 12.2.0, Node.js 16.13.1, Prisma 4, Postgres 14.3, TypeScript 4.7.4, React Query 4-beta, Axios, React Hook Form 8-alpha, React Dropzone, Zod, msw, TailwindCSS 3, Jest 28, Testing Library React, Cypress 9.6.1.

Frontend:

Backend:

Testing:

Development:

Production:

CI/CD:

Documentation:

Core principles:

Lighthouse score:

Without any special adjustments, there is room for further improvement.

Development environment

This project has 3 available development environments:

  1. local
  2. Docker (with and without devcontainers)
  3. Gitpod

You can pick whatever environment you prefer.

Which one to choose? If you like conventional approach pick local, if you work in a team and want to have consistent environments with colleagues to easily reproduce bugs and quickly onboard new members pick Docker, and if you want to make sandbox do reproduce a bug and ask for help publicly pick Gitpod.

1. local environment

Clone repository and install dependencies.

# clone repository
git clone git@github.com:nemanjam/nextjs-prisma-boilerplate.git
cd nextjs-prisma-boilerplate

# install dependencies
yarn install

When you open project folder for the first time VS Code will ask you to install recommended extensions, you should accept them all, they are needed to highlight, autocomplete, lint and format code, run tests, manage containers.

Fill in required public environment variables in .env.development. Fastest way is to run the app with http server.

You need https locally only for Facebook OAuth login. For that you need mkcert to install certificates for localhost, instructions for that you can find in docs folder.

Leave PORT as 3001, it is hardcoded in multiple places, if you want to change it you must edit all of them (i.e. all Dockerfile.* and docker-compose.*.yml)

# .env.development

SITE_PROTOCOL=http
SITE_HOSTNAME=localhost
PORT=3001

# don't touch these two variables
APP_ENV=local
NEXTAUTH_URL=${SITE_PROTOCOL}://${SITE_HOSTNAME}:${PORT}

Create .env.development.local file.

# create local file form example file
cp .env.development.local.example .env.development.local

In all environments Postgres container is configured to run as a current non-root user on a Linux host machine. This is important so that database files in volumes are created with correct ownership and permissions. For this you need to define MY_UID and MY_GID. Best place to set them is in ~/.bashrc.

# ~/.bashrc
export MY_UID=$(id -u)
export MY_GID=$(id -g)

Fill in required private environment variables. The only required variables are for Postgres database connection and JWT secret.

Facebook and Google credentials are optional and used only for OAuth login. Facebook login requires https for redirect url. You can set any values for POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB.

# .env.development.local

# set database connection
POSTGRES_HOSTNAME=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres_user
POSTGRES_PASSWORD=password
POSTGRES_DB=npb-db-dev

# don't edit this expanded variable
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOSTNAME}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public

# jwt secret
SECRET=some-long-random-string

# OAuth logins (optional)
# Facebook (you need https for this)
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

After all variables are set you can run Postgres database inside the Docker container, run Prisma migrations that will create SQL tables from schema.prisma and seed database with data.

# run database container
yarn docker:db:dev:up

# run Prisma migrations (this will create sql tables, database must be running)
yarn prisma:migrate:dev:env

# seed database with data
yarn prisma:seed:dev:env

At this point everything is ready, you can now start the app. Open http://localhost:3001 in the browser to see the running app.

# start the app in dev mode
yarn dev

Docker environment

After you cloned repository build app container.

# terminal on host
yarn docker:dev:build

Docker environment will read variables from envs/development-docker folder. Create local env file from example file. It has all variables configured already.

# terminal on host
cp envs/development-docker/.env.development.docker.local.example envs/development-docker/.env.development.docker.local

Run the app, database and Adminer containers. That's it. Project folder is mounted to /app folder inside container, you can either edit source directly on host or open Remote containers extension tab and right click npb-app-dev and select Attach to Container and open /app folder in remote VS Code instance. Open http://localhost:3001 in the browser on host to see the running app.

# terminal on host
yarn docker:dev:up

Open new terminal inside the container and seed the database, docker-compose.dev.yml already passes correct env files.

# terminal inside the container
yarn prisma:seed

Note: Git will already exist in container with your account so you can commit and push changes directly from container.

# check that git config is already set inside the container
git config --list --show-origin

I suggest you install Portainer Community Edition container locally for easier managing and debugging containers, it's free and very useful tool.

Gitpod environment

Go to elephantsql.com create free account and create free 20MB Postgres database. Go to gitpod.io, login with Github. Open your forked repository in Gitpod by opening following link (replace your-username with real one):

https://gitpod.io/#https://github.com/your-username/nextjs-prisma-boilerplate

Gitpod environment will read variables from envs/development-gitpod folder. Create local env file from example file.

# terminal on Gitpod
cp envs/development-gitpod/.env.development.gitpod.local.example envs/development-gitpod/.env.development.gitpod.local

In that local file set the database url from elephantsql.com. Other variables are set automatically.

# envs/development-gitpod/.env.development.gitpod.local
DATABASE_URL=postgres://something:something@tyke.db.elephantsql.com/something

Now migrate and seed the database.

Note: elephantsql.com database doesn't have all privileges so you must use prisma push command instead of usual prisma migrate dev. Read more details about shadow database in docs/demo-environments.md.

# terminal on Gitpod

# migrate db
yarn gitpod:push:env

# seed db
yarn gitpod:seed:env

Everything is set up, you can now run the app in dev mode and open it in new browser tab.

yarn gitpod:dev:env

Running tests

This project has 4 separate testing configurations plus code coverage configuration. All tests can run locally, in Docker and in Github Actions.

  1. Client unit and integration tests - Jest and React Testing Library
  2. Server unit tests - Jest
  3. Server integration tests - Jest and test database
  4. Code coverage report - all Jest tests and test database
  5. E2E tests - Cypress, app running in production mode and test database

Note: You can also run and debug all Jest tests with orta.vscode-jest extension that is already included in recommended list.

1. Running client unit and integration tests

Running locally.

yarn test:client

Running in Docker.

yarn docker:test:client

2. Running server unit tests

Running locally.

yarn test:server:unit

Running in Docker.

yarn docker:test:server:unit

3. Running server integration tests

Make sure that test database is up and migrated. You don't need to seed it.

# run database container
yarn docker:db:test:up

# migrate test database
yarn prisma:migrate:test:env

Running locally.

yarn test:server:integration

Running in Docker.

yarn docker:test:server:integration

4. Running code coverage report

You need running test database, same as in previous step.

Running locally.

yarn test:coverage

Running in Docker.

yarn docker:test:coverage

5. Running E2E tests with Cypress

Running locally:

You need to run and migrate test database (no need for seed), build app for production, run the app and run Cypress.

# run database container
yarn docker:db:test:up

# migrate test database
yarn prisma:migrate:test:env

Then you need to build app for production.

# build the app for prod
yarn build

Then you need to start both app and Cypress at same time. This will open Cypress GUI.

# starts the app and Cypress GUI
yarn test:e2e:env

You can also run Cypress in headless mode (without GUI).

# starts the app and Cypress in headless mode
yarn test:e2e:headless:env

Running in Docker:

Build both app and Cypress images.

# build testing app image
yarn docker:npb-app-test:build

# build Cypress container
yarn docker:npb-e2e:build

Then you can run test database, test app container and Cypress (in headless mode) container at once.

# run db, app and Cypress headless
yarn docker:npb-e2e:up

Deployment to production

I made a separate repository nemanjam/traefik-proxy only for deployment with Traefik reverse proxy that needs only environment variables and image from Dockerhub. There are also Github Actions workflows to build, push and redeploy latest image on your server. You should use that for deployment.

For the sake of completeness I described here how to build and run production app locally and in Docker. These two can be useful as staging environments for testing. I also described how to build and push live image to Dockerhub from your local development machine.

Build and run production app locally

When building and running app in production mode it will read variables from .env.production and .env.production.local. At build time the only required variable is NEXTAUTH_URL (it is used for base url in CustomHead component responsible for SEO). If you use getStaticProps (Static Site Generation) you will need to pass DATABASE_URL too with correct data. At runtime you need to define all public and private variables in these two files.

To build and run production app run these two commands.

# build app
yarn build

# start app
yarn start

Build and run production app in Docker

When building production app inside a Docker image again you need to pass same variables like locally (NEXTAUTH_URL and DATABASE_URL for SSG), this time these are forwarded with ARG_NEXTAUTH_URL and ARG_DATABASE_URL in Dockerfile.prod. This time environment variables are read from envs/production-docker/.env.production.docker and envs/production-docker/.env.production.docker.local. At runtime you need to define all public and private variables in these two files.

To build and run Docker production image run this.

# build production image
yarn docker:prod:build:env

# run production image
yarn docker:prod:up

Build and push Docker live production image locally

Again you need to set NEXTAUTH_URL and DATABASE_URL (for SSG) this time in envs/production-live/.env.production.live.build.local. Create this file from example file.

cp envs/production-live/.env.production.live.build.local.example envs/production-live/.env.production.live.build.local

You need to edit this yarn script and set your real Dockerhub username and image name.

# replace your-dockerhub-username and your-image-name with yours

"docker:live:build": "dotenv -e ./envs/production-live/.env.production.live.build.local -- bash -c 'docker build -f Dockerfile.prod -t your-dockerhub-username/your-image-name:latest --build-arg ARG_DATABASE_URL=${DATABASE_URL} --build-arg ARG_NEXTAUTH_URL=${NEXTAUTH_URL} .'",

You can now build, tag and push to Dockerhub your production image. To push image you must first login in terminal with docker login.

# build and tag production image
yarn docker:live:build

# push image to Dockerhub
yarn docker:live:push

Build and push Docker live production image in Github Actions (preferred)

There is already set up workflow to build and push production image in Github Actions in .github/workflows/build-docker-image.yml. In your repository settings you just need to set these variables and run workflow.

# your dockerhub username
DOCKERHUB_USERNAME
# your dockerhub password
DOCKERHUB_TOKEN
# database url (only for SSG)
NPB_DATABASE_URL
# your live production app url (without trailing '/')
# i.e. https://subdomain.my-domain.com
NPB_NEXTAUTH_URL

Run live production app on VPS with Traefik

You just need to set your image name inside docker-compose.live.yml, pass all environment variables to it and deploy it with docker-compose up -d on your server.

# docker-compose.live.yml

services:
  npb-app-live:
    container_name: npb-app-live
    image: your-dockerhub-username/your-image-name:latest

For this purpose I already made separate repository nemanjam/traefik-proxy with Traefik reverse proxy that allows you to host multiple apps inside Docker containers where each container expose different port and Traefik maps ports to subdomains. For details how to configure this see README.md file and linked tutorial in it. You just need to run your app container and Traefik will automatically pick it up without you needing to restart Traefik's container manually.

Beside Traefik it also already has portainer container for managing containers, adminer container for administering production database, uptime-kuma for tracking website uptime, and another postgres container configured to accept connections from remote hosts (useful for building app in Github Actions).

Bellow are listed all environments variables you need to set. For sake of simplicity I showed you here how to set them in local .env file, docker-compose.yml file will read it and forward all needed variables into containers. This is ok for demo apps but for real production apps proper way to do this is to set them in your cloud provider's dashboard or use some dedicated vault.

# create .env file locally and set vars
cp apps/nextjs-prisma-boilerplate/.env.example apps/nextjs-prisma-boilerplate/.env

# copy populated local .env file to server securely with ssh
scp ./apps/nextjs-prisma-boilerplate/.env ubuntu@your-server:~/traefik-proxy/apps/nextjs-prisma-boilerplate

These are all needed variables.

MY_UID and MY_GID are id's of your current user and group on your Linux server. You can see their values by running id -u and id -g in your server's terminal. The best place to set them is globally in ~/.bashrc because they can be needed for multiple containers. They are passed into Postgres container so that volume data files are created with correct permissions and ownership (as current user and not root user).

# apps/nextjs-prisma-boilerplate/.env

# public vars bellow

APP_ENV=live

# http node server in live, Traefik handles https
SITE_PROTOCOL=http

# real full production public domain (with subdomain), used in app and Traefik
SITE_HOSTNAME=nextjs-prisma-boilerplate.nemanjamitic.com
PORT=3001

# real url is https and doesn't have port, Traefik handles https and port
NEXTAUTH_URL=https://${SITE_HOSTNAME}

# private vars bellow

# db container
POSTGRES_HOSTNAME=npb-db-live
POSTGRES_PORT=5432
POSTGRES_USER=postgres_user
POSTGRES_PASSWORD=
POSTGRES_DB=npb-db-live

# don't edit this
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOSTNAME}:${POSTGRES_PORT}/${POSTGRES_DB}?schema=public

# current host user as non-root user in Postgres container, set it here
MY_UID=1001
MY_GID=1001

# or better globally in ~/.bashrc
# export MY_UID=$(id -u)
# export MY_GID=$(id -g)

# jwt secret
SECRET=some-long-random-string

# Facebook
FACEBOOK_CLIENT_ID=
FACEBOOK_CLIENT_SECRET=

# Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Redeploy latest Docker live production image on VPS

To avoid manual work there is already Github Actions workflow in .github/workflows/deploy.yml that will remove old image and pull and run latest image from Dockerhub using ssh action. All you need to do is to trigger it either manually or chain it on existing build and push workflow.

# .github/workflows/deploy.yml

# trigger redeploy with build workflow
on:
  workflow_run:
    workflows: ['docker build']

Documentation

There is an extensive documentation for this project in docs folder. You can find all technical aspects carefully documented, especially important and difficult parts. There you can find problem descriptions, solutions, code snippets and related linked references.

Currently documentation is bare in a sense that it holds only bare technical information how to solve something and it's not rounded in human friendly articles with additional context.

Here is the brief overview of what you can find in it:

Contributing

Contributions are welcome. You can find more info how to contribute in contributing.

Roadmap

Known issues

Related projects

Motivation

There are a lot of talk, theory, opinions, and buzz around JavaScript frameworks... but lets stop talking, pick the most popular framework, read what they suggest in documentation and try it out in practice, check how it works and see if we can build something useful and meaningful with it.

Author

nemanjam, Linkedin

References

Complete references links are attached in docs files. Most important references are:

License

This project uses MIT license: License