Skip to content

README.md

Latest commit

 

History

History
275 lines (210 loc) · 7.07 KB

README.md

File metadata and controls

275 lines (210 loc) · 7.07 KB

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