MongoDB Atlas Starter

-> View demo: nextjs.mongodb.com

Next.js with MongoDB

A minimal, production-ready template for building full-stack React applications with Next.js (App Router), the MongoDB Node.js driver, TypeScript, and Tailwind CSS / shadcn/ui. Use it as a starting point for full-stack apps backed by MongoDB Atlas, with one-click deployment to Vercel.

Features

• Next.js 16 App Router with React 19 and server components
• MongoDB integration via the official Node.js driver with a shared client singleton
• Live connection status badge on the home page (server-side ping health check)
• TypeScript throughout, with strict mode enabled
• Tailwind CSS + shadcn/ui components for styling
• One-click Vercel deploy with the MongoDB Atlas integration
• End-to-end tests (Playwright) and CI (GitHub Actions) against a real MongoDB

Tech Stack

Architecture Overview

The home page (app/page.tsx) is a server component. On render it calls dbConnectionStatus() (db/connection-status.ts), which uses the shared MongoDB client from lib/mongodb.ts to run a ping command and report whether the database is reachable. The result is shown as a status badge in the UI.

Loading diagram...

Getting Started

Click the "Deploy" button to clone this repo, create a new Vercel project, setup the MongoDB integration, and provision a new MongoDB database:

Local Setup

Prerequisites

• Node.js 20 or later
• A MongoDB connection string (from MongoDB Atlas or a local MongoDB instance)

Installation

Install the dependencies:

1
npm install

Development

Create a .env file in the project root

1
cp .env.example .env

Get your database URL

Obtain the database connection string from the Cluster tab on the MongoDB Atlas Dashboard.

Add the database URL to the .env file

Update the .env file with your database connection string:

1
MONGODB_URI=mongodb+srv://<username>:<password>@<cluster-url>/<database>?retryWrites=true&w=majority

Start the development server

1
npm run dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

Environment Variables

Create a .env file from the example (cp .env.example .env) and set:

Project Structure

• app/ — Next.js App Router pages, layout, and global styles (app/page.tsx is the home page)
• db/connection-status.ts — server-side MongoDB connection health check
• lib/mongodb.ts — MongoDB client singleton (sets the appName connection metadata)
• components/ui/ — shadcn/ui components
• tests/e2e/ — Playwright end-to-end tests
• .github/workflows/ci.yml — CI pipeline (build + e2e against MongoDB)
• AGENTS.md / EDD.md — guidance for AI agents and the MongoDB data model

Testing

End-to-end tests use Playwright and run against a real MongoDB instance. They require MONGODB_URI to be set and the Playwright browser installed.

1
# one-time: install the browser
2
npx playwright install --with-deps chromium
3

4
# run the end-to-end suite (starts the app automatically)
5
MONGODB_URI="mongodb://localhost:27017/nextjs_template" npm run test:e2e

Expected result: the suite renders the home page and asserts the status badge shows Database connected. The same suite runs in CI on every push and pull request via GitHub Actions, using a mongo service container.

Troubleshooting

• Badge shows "No MONGODB_URI environment variable" — create .env (cp .env.example .env) and set MONGODB_URI, then restart the dev server.
• Badge shows "Database not connected" — verify the connection string, that your IP is allow-listed in Atlas Network Access, and that the database user and password are correct.
• e2e tests fail to start the server — ensure nothing else is using port 3000, or set PORT before running the tests.
• Playwright "browser not found" — run npx playwright install --with-deps chromium.

Learn More

To learn more about MongoDB, check out the MongoDB documentation:

• MongoDB Documentation - learn about MongoDB features and APIs
• MongoDB Node.js Driver - documentation for the official Node.js driver

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API
• Learn Next.js - an interactive Next.js tutorial

Deploy on Vercel

Commit and push your code changes to your GitHub repository to automatically trigger a new deployment.