Next.js Prisma Boilerplate

Next.js Prisma Boilerplate is a full-stack starter project for building small-to-medium web apps on a single Linux box, built around Next.js 12, Prisma 4, Postgres, TypeScript, Tailwind CSS, and Docker. It pairs a live demo with production deployment to a VPS via Traefik and includes complete frontend and backend test suites.

What is Next.js Prisma Boilerplate?

This boilerplate is a production-ready starting point that combines a Next.js 12 app (React 18.2.0) with a Prisma/Postgres backend, authentication via next-auth, and a decoupled controller-service API layer. It takes environment variables for database connection and OAuth credentials as input and outputs a running web app with CRUD features, responsive theming, and full test coverage. It is maintained by developer Nemanja Mitić (nemanjam) and uses the MIT license.

Key Features

• Authentication — next-auth with Credentials, Google, and Facebook providers, configured for both local HTTP and HTTPS OAuth redirects.
• Full Next.js stack — uses routing, SSR, SEO via a CustomHead component, Image component, custom HTTP server, and .env* file handling.
• Responsive UI and theming — TailwindCSS 3 with custom Tailwind plugin for themes, SCSS and BEM naming, no !important statements anywhere.
• Data layer — Prisma 4 ORM on Postgres 14.3 with User and Post models, offset-based pagination, full-text search, and a Faker seed script.
• Backend architecture — next-connect API handlers with middleware for validation and protected routes, controller-service layers, Zod-validated request objects reused on the client, and global error handling for API and getServerSideProps.
• Testing suite — Jest (3 project configs: client, server unit, server integration) with React Testing Library, Mock Service Worker, Supertest, and code coverage; Cypress 9.6.1 E2E tests with a custom Docker image.
• Development environments — three configured setups: local, Docker (VS Code devcontainers), and Gitpod, each with Postgres and Adminer containers.
• CI/CD and deployment — three GitHub Actions workflows (tests, Docker image build/push, VPS deployment via SSH), plus a separate Traefik proxy repository for hosting on a VPS.

Who is it for?

• Developers who want to skip architecture decisions and start coding features on day one, using a preconfigured stack with auth, database, forms, and tests.
• Small teams looking for consistent Docker-based development environments so bugs reproduce and onboarding is fast.
• Full-stack learners wanting a working reference of Next.js + Prisma best practices with documented notes and links in the docs folder.

What can you do with it?

• Build a blog, social network, e-commerce, or SaaS — the boilerplate includes User and Post models with CRUD APIs and a responsive frontend to extend.
• Reuse specific design decisions — for example, the VS Code devcontainer setup works for any Node.js project, and the theming plugin or email/password login can be lifted independently.
• Learn from documented working examples — the docs folder covers Next.js, next-auth, React Query, React Hook Form, Prisma, Docker, Cypress, and more.

How does it work?

Clone the repository, install dependencies with Yarn, set environment variables in .env.development and .env.development.local, then run Postgres in Docker and apply Prisma migrations. After seeding the database, yarn dev starts the app at http://localhost:3001, and tests run via yarn test:client, yarn test:server:unit, yarn test:server:integration, or Cypress with yarn test:e2e:env.

Known limitations

• Hydration error in development — refreshing a page sometimes triggers a Suspense hydration error, documented in a GitHub issue.
• Hardcoded port — PORT is set to 3001 and referenced in multiple Dockerfiles and compose files, so changing it requires editing all of those places.
• Not serverless out of the box — the custom HTTP server and single-container production image mean serverless deployment requires removing the custom server and adjusting upload storage.

Pricing

The project is free and open source under the MIT license.

FAQ

Is Next.js Prisma Boilerplate free?

Yes, the boilerplate is released under the MIT license, so you can use, modify, and distribute it for personal or commercial projects without license fees.

Does it support OAuth login?

Yes. next-auth is configured with Credentials (email/password), Google, and Facebook providers. Facebook login requires HTTPS locally, which you can set up with mkcert.

Can I deploy it serverless?

Partially. The project uses a custom HTTP server and a single Docker container for production, so going serverless requires removing the custom server, choosing a different Multer storage type for uploads, and not using the single-container Docker setup.

Is there a live demo?

Yes, a production demo is available at https://nextjs-prisma-boilerplate.arm1.nemanjamitic.com, and a Gitpod workspace snapshot lets you try the development environment in the browser.

How long does setup take?

The README claims you can install the boilerplate in about 15 minutes: clone, install dependencies, set environment variables, run the database via Docker, migrate, seed, and start with yarn dev.