NextBase

NextBase is a modern full-stack Next.js 16 starter built to be the base for future projects.

The goal is simple:

a production-ready starter that shows strong full-stack structure without turning into a bloated template

It is intended to work both as:

• a portfolio project that shows architecture and real-world tooling
• a reusable base for future apps, dashboards, and SaaS-style products

Why This Exists

Most starters either:

• look good but stop at frontend polish
• add too many libraries too early
• skip the boring production details that actually matter

NextBase is meant to stay in the middle:

• strong routing and layout structure
• real auth and database setup
• reusable UI primitives
• production-aware scripts and tooling
• clear room to grow without overbuilding from day one

Feature Highlights

• Next.js 16 App Router server components, nested layouts, route groups, API routes
• Better Auth email/password auth with verification, reset flow, and protected dashboard flows
• Drizzle ORM + Postgres typed schema and database access
• shadcn/ui + Tailwind CSS 4 reusable components and scalable styling
• Typed Environment Validation shared env parsing for safer config usage
• SEO and Sitemap Setup sitemap generation and metadata-ready structure
• Email Delivery Setup Resend for production, React Email templates, Mailpit for local SMTP capture
• Performance Tooling build verification and Lighthouse scripts
• Testing Coverage Jest component/page tests and Playwright smoke tests for core auth flows
• Responsive Layout Foundation split auth and dashboard layouts, reusable nav components

Stack

• Next.js 16
• React 19
• TypeScript
• Tailwind CSS 4
• shadcn/ui
• Better Auth
• Drizzle ORM
• Neon Postgres serverless
• UploadThing
• Zod
• Resend
• React Email
• Mailpit

Project Structure

src/
  app/          routes, layouts, API routes
  components/   reusable UI and layout components
  config/       shared config such as env parsing
  db/           database client and schema
  hooks/        client hooks
  lib/          auth client, auth server, utilities
  styles/       global styles
  utils/        feature-specific utilities

Getting Started

Install dependencies:

bun install

Create a local env file:

DATABASE_URL=postgres://username:password@host:port/dbname
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-secret
UPLOADTHING_TOKEN=your-token
EMAIL_PROVIDER=smtp
EMAIL_FROM=NextBase <noreply@example.com>
RESEND_API_KEY=
SMTP_HOST=127.0.0.1
SMTP_PORT=1025
SMTP_SECURE=false
SMTP_USER=
SMTP_PASS=
MAILPIT_WEB_URL=http://localhost:8025
ANALYZE=false

Run the app:

bun run dev

Scripts

bun run typecheck
bun run lint
bun run build
bun run postbuild
bun run test
bun run test:components
bun run test:e2e
bun run db:generate
bun run db:push
bun run email:dev
bun run mailpit:up
bun run mailpit:down
bun run lighthouse:dev
bun run lighthouse:prod

Email Setup

Local development

Local development defaults to SMTP. Mail is sent to Mailpit instead of a real inbox.

Start Mailpit:

bun run mailpit:up

Mailpit UI:

http://localhost:8025

SMTP host used by the app:

127.0.0.1:1025

Preview email templates during development:

bun run email:dev

Production

For production, set:

EMAIL_PROVIDER=resend
EMAIL_FROM=Your App <noreply@yourdomain.com>
RESEND_API_KEY=your_resend_api_key

The current auth flow uses this mail setup for password reset emails. It also handles email verification on sign up and resend-on-sign-in for unverified users.

Current Status

Done

• Next.js App Router structure is in place
• Better Auth is integrated
• email/password auth supports sign up, login, forgot password, reset password, and email verification
• resend verification and post-reset confirmation email flows are wired
• Drizzle database client and schema setup exist
• auth and dashboard layouts are split
• app-level error boundaries and not-found pages are in place
• reusable UI components are scaffolded with shadcn/ui
• mobile nav exists
• empty state component exists
• typed env validation is added
• Resend + React Email + Mailpit setup is added
• email verification is added
• UploadThing avatar upload is connected to the profile page
• admin route and role-aware dashboard navigation are in place
• the shared providers layer is cleaned up and consistently named
• Jest covers auth pages and key UI primitives
• Playwright smoke tests cover homepage, auth entry points, and protected dashboard access
• primary marketing, docs, support, and legal routes are in place so navigation is complete
• dashboard placeholder routes exist for analytics, projects, and notifications instead of dead links
• sitemap generation works
• Lighthouse scripts work
• lint, typecheck, build, component tests, and Playwright smoke tests are green
• /reset-password suspense issue is fixed

Next Up

• expand test coverage for admin actions, profile flows, and email-driven auth paths
• replace placeholder dashboard content with product-specific data once the first real app feature lands
• decide whether to keep Jest long term or consolidate on Vitest
• keep README claims aligned with actual implementation

Planned Features

• richer admin actions on top of the Better Auth admin plugin
• stronger empty and error states in dashboard flows
• react-hook-form only if forms become complex enough to justify it
• a minimal API layer only if repeated fetch logic appears
• reducing dependency surface where features are not clearly demonstrated

Scope

This repo is intentionally not trying to be everything at once.

What it should be:

• a solid base for future full-stack projects
• a template that demonstrates architecture and engineering judgment
• something portfolio-worthy because it shows real implementation choices

What it should not become:

• a dumping ground for random dependencies
• an unfinished SaaS with every possible feature half-added
• a template that is harder to understand than the projects built on top of it

Portfolio Value

If done well, this project should clearly show:

• full-stack capability, not just frontend styling
• practical auth and database integration
• maintainable layout and component structure
• production-aware tooling and scripts
• restraint in what gets added and why

That matters more than feature count.

Deployment

Recommended target: Vercel for app hosting, with Postgres managed separately.

Typical production flow:

bun run lint
bun run typecheck
bun run build
bun run postbuild

Notes

• Avoid adding state libraries unless there is a clear need.
• Avoid adding large systems like payments, chat, notifications, or full RBAC too early.
• Prefer proving architecture, auth, data, and delivery quality over raw feature count.

References

• Next.js Docs
• shadcn/ui
• Drizzle ORM Docs
• Better Auth Docs
• UploadThing Docs