This template provides a robust, type-safe, and scalable foundation for building modern web applications. It leverages the Next.js App Router, secures access using Auth.js, and uses Drizzle ORM for database interaction with Neon's serverless infrastructure.
It focuses on best practices, ensuring end-to-end TypeScript safety, secure environment variable handling, and automated database schema management using Drizzle migrations.
This quickstart is built on a strong, modern foundation:
- Next.js (App Router): High performance, server-side capabilities, and API routes.
- TypeScript: Full type safety across the entire stack, from UI down to the database.
- Tailwind CSS: Rapid, utility-first, and responsive UI development.
- Auth.js (NextAuth): Flexible, secure session management and simple integration of OAuth providers.
- Drizzle ORM: A modern, TypeScript ORM for SQL, providing excellent type inference and easy migrations.
- Neon: A serverless Postgres database that is fully managed, scalable, and cost-effective, using serverless drivers.
The key features of this template are:
- Next.js App Router: Utilizes modern features like Server Components and Server Actions.
- Full Type Safety: Types defined once in the Drizzle schema flow directly through to API routes and React components.
- Secure Authentication: Ready-to-go setup for Auth.js using the Drizzle Adapter.
- Database Migrations: Simple process for evolving the database schema safely.
- Scalable Architecture: Designed for deployment on Vercel with serverless functions and Neon connection pooling.
Before you start, ensure you have the following installed:
- Node.js (v18.x or later)
- npm (the default package manager)
- A Neon account (or a PostgreSQL instance)
- GitHub/Google OAuth credentials (if using external sign-in)
git clone <repository-url>
cd nextjs-drizzle-neon-quickstart
npm install
2. Configure Environment Variables
Create a file named .env in the root of the project. You must fill in the necessary configuration details:
Variable Description Example/Notes
DATABASE_URL Connection string for your Neon Postgres database. Must include connection pooling! .../yourdb?sslmode=require&connection_options=-c%20statement_timeout%3D10000
NEXTAUTH_SECRET A long, complex string to sign session cookies. Generate using: openssl rand -base64 32
NEXTAUTH_URL The public URL of your deployment. http://localhost:3000 or your Vercel URL
GITHUB_ID & GITHUB_SECRET Credentials for GitHub OAuth. Replace with your chosen provider's credentials if necessary.
3. Database Setup (Drizzle Migrations)
This quickstart uses Drizzle Kit to manage your schema and migrations.
A. Define Your Schema
The database schema is defined in src/db/schema.ts. Modify this file to add tables and relationships as needed.
B. Generate a Migration
When you change the schema, generate a new migration file by running:
Bash
npm run db:generate
This creates a new timestamped file in the drizzle/ directory that captures the changes.
C. Apply Migrations
To run the generated migration files against your live Neon database, execute:
Bash
npm run db:migrate
⚠️ Warning: Only run this command once you are certain about your schema changes, as it modifies the database structure.
4. Run the Development Server
Once the environment variables are set and the database is migrated, you can start the application:
Bash
npm run dev
Open http://localhost:3000 in your browser.