Next.js Starter Template

A production-ready Next.js 15 starter template with authentication, form handling, and a scalable architecture.

🚀 Features

⚡ Next.js 15.5 with App Router and Turbopack
🔐 Authentication - Cookie-based auth with protected routes
📝 Form Handling - TanStack Form + Zod validation
🎨 UI Components - shadcn/ui + Tailwind CSS 4
🔄 State Management - TanStack Query v5 + Zustand for client state
🎯 TypeScript - Full type safety with enums
🪝 Custom Hooks - Reusable logic patterns
📱 Responsive - Mobile-first design
🌙 Toast Notifications - Sonner for user feedback
🎨 Theme Support - Next Themes for dark/light mode

📦 Tech Stack

Framework: Next.js 15.5.6
Language: TypeScript 5
Styling: Tailwind CSS 4 + tw-animate-css
UI Library: Radix UI + shadcn/ui
Forms: TanStack Form 1.23 + Zod 4.1
Data Fetching: TanStack Query 5.90 + Axios 1.13
State Management: Zustand 5.0
Icons: Lucide React
Notifications: Sonner 2.0

🏁 Getting Started

Prerequisites

Node.js 20+ and pnpm (or npm/yarn/bun)
Docker (optional, for containerized deployment)

Installation

Clone the repository

git clone <your-repo-url>
cd nextjs-template

Install dependencies

pnpm install

Set up environment variables

cp .env.example .env

Edit .env with your configuration.

Run the development server

pnpm dev

Open http://localhost:3000

The app will hot-reload as you edit files.

📁 Project Structure

nextjs-template/
├── src/
│   ├── app/                    # Next.js App Router (routes & API)
│   │   ├── page.tsx           # Home page (/)
│   │   ├── layout.tsx         # Root layout
│   │   ├── globals.css        # Global styles
│   │   ├── favicon.ico        # App favicon
│   │   ├── auth/              # Auth routes (/auth/*)
│   │   │   ├── page.tsx       # Auth wrapper page
│   │   │   ├── login/         # Login page
│   │   │   └── register/      # Register page
│   │   ├── user/              # Protected routes (/user/*)
│   │   │   └── page.tsx       # User dashboard
│   │   └── api/               # API endpoints
│   │       └── auth/          # Auth API routes
│   │           ├── login/     # POST /api/auth/login
│   │           ├── register/  # POST /api/auth/register
│   │           ├── logout/    # POST /api/auth/logout
│   │           └── me/        # GET /api/auth/me
│   ├── modules/                # Feature modules
│   │   ├── auth/              # Auth feature
│   │   │   ├── auth-page.tsx  # Auth layout component
│   │   │   └── _components/   # Private auth components
│   │   │       ├── login-form.tsx
│   │   │       └── register-form.tsx
│   │   ├── home/              # Home page feature
│   │   │   └── home-page.tsx
│   │   └── user/              # User dashboard feature
│   │       └── dashboard-page.tsx
│   ├── components/             # Reusable UI components
│   │   ├── ui/                # shadcn/ui base components
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── field.tsx
│   │   │   ├── input.tsx
│   │   │   ├── input-group.tsx
│   │   │   ├── label.tsx
│   │   │   ├── separator.tsx
│   │   │   ├── sonner.tsx
│   │   │   ├── tabs.tsx
│   │   │   └── textarea.tsx
│   │   └── custom/            # Custom components
│   │       └── link.tsx
│   ├── hooks/                  # Custom React hooks
│   │   ├── index.ts           # Hooks barrel export
│   │   └── use-toggle.ts      # Toggle hook
│   ├── services/               # API service layer (TanStack Query)
│   │   ├── auth-queries.ts    # Read operations (GET)
│   │   └── auth-mutations.ts  # Write operations (POST/PUT/DELETE)
│   ├── schemas/                # Zod validation schemas
│   │   └── auth.schema.ts     # Auth form schemas
│   ├── types/                  # TypeScript type definitions
│   │   └── auth.type.ts       # Auth types
│   ├── enums/                  # TypeScript enums
│   │   └── user-role.enum.ts  # User role enum
│   ├── store/                  # Zustand stores for client state
│   │   ├── index.ts           # Store barrel export
│   │   └── counter.store.ts   # Example counter store
│   ├── lib/                    # Utilities and configured libraries
│   │   ├── axios.ts           # Axios instance config
│   │   └── utils.ts           # Utility functions (cn, etc.)
│   ├── providers/              # React context providers
│   │   └── react-query-provider.tsx
│   └── middleware.ts           # Next.js middleware (auth protection)
├── public/                     # Static assets
└── ...config files             # See below for details

⚙️ Configuration Files

File	Purpose
`next.config.ts`	Next.js configuration
`tsconfig.json`	TypeScript configuration
`tailwind.config.ts`	Tailwind CSS configuration
`postcss.config.mjs`	PostCSS configuration
`eslint.config.mjs`	ESLint configuration
`.prettierrc`	Prettier code formatting
`components.json`	shadcn/ui configuration
`dockerfile`	Docker image definition
`docker-compose.yml`	Docker Compose setup
`.env.example`	Environment variables template

📂 Folder Purposes

Folder	Purpose	Example
`/app`	Next.js routes and API endpoints	`app/auth/login/page.tsx`
`/modules`	Feature-specific code	`modules/auth/_components/login-form.tsx`
`/components`	Reusable UI components	`components/ui/button.tsx`
`/hooks`	Custom React hooks	`hooks/use-toggle.ts`
`/services`	API calls with TanStack Query	`services/auth-mutations.ts`
`/schemas`	Zod validation schemas	`schemas/auth.schema.ts`
`/types`	TypeScript types	`types/auth.type.ts`
`/store`	Zustand stores for client state	`store/counter.store.ts`
`/providers`	React context providers	`providers/react-query-provider.tsx`

Key Conventions

Files/Folders: kebab-case (e.g., login-form.tsx)
Components: PascalCase (e.g., LoginForm)
Functions/Variables: camelCase (e.g., useAuthLogin)
Private folders: _components/ (module-specific, not reusable)
Imports: Use @/ alias (e.g., import { Button } from '@/components/ui/button')

🛠️ Available Scripts

pnpm dev          # Start development server with Turbopack
pnpm build        # Build for production with Turbopack
pnpm start        # Start production server
pnpm lint         # Run ESLint

Note: This template uses Turbopack for both development and production builds for faster performance.

🔑 Authentication Flow

This template includes a complete authentication system:

Login/Register - Forms with validation at /auth/login and /auth/register
Cookie-based Auth - HTTP-only cookies for security
Protected Routes - Middleware protects /user/* routes
Auto-redirect - Logged-in users can't access auth pages
User Query - useAuthUser() hook fetches current user

API Routes

POST /api/auth/login - User login
POST /api/auth/register - User registration
POST /api/auth/logout - User logout
GET /api/auth/me - Get current user

🎨 Adding New Features

Example: Adding a Blog Feature

Create module structure:

mkdir -p src/modules/blog/_components

Create page component:

// src/modules/blog/blog-page.tsx
export default function BlogPage() {
  return <div>Blog</div>;
}

Create route:

// src/app/blog/page.tsx
import BlogPage from '@/modules/blog/blog-page';
export default BlogPage;

Add services, schemas, and types as needed:

src/services/blog-queries.ts
src/services/blog-mutations.ts
src/schemas/blog.schema.ts
src/types/blog.type.ts

🧩 Custom Hooks

`useToggle`

Toggle boolean state with ease:

import { useToggle } from '@/hooks';

const [isOpen, toggle] = useToggle(false);

<Button onClick={toggle}>Toggle</Button>

🔢 Enums

Note: The enums in src/enums/ are provided as examples. Replace or extend them to fit your application's needs.

TypeScript enums are placed in the src/enums/ folder for better organization.

`UserRole` Enum

Define user roles with helper functions:

import { UserRole, isAdminRole } from '@/enums/user-role.enum';

const userRole = UserRole.ADMIN;
if (isAdminRole(userRole)) {
    // Admin-specific logic
}

🗂️ State Management

Zustand Stores

Note: The store in src/store/ is provided as an example. Replace or extend it with your own stores as needed.

Client-side state is managed with Zustand stores in src/store/.

Counter Store Example

import { useCounterStore } from '@/store';

function CounterComponent() {
    const { count, increment, decrement, reset } = useCounterStore();

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={increment}>+</button>
            <button onClick={decrement}>-</button>
            <button onClick={reset}>Reset</button>
        </div>
    );
}

When to Use Zustand vs TanStack Query

Zustand: Client-side state (UI state, local preferences, temporary data)
TanStack Query: Server state (API data, caching, synchronization)

Why separate `modules/` and `components/`?

Modules = Feature-specific components (used once)
Components = Reusable components (used across features)

Why separate queries and mutations?

Clearer separation of read vs write operations
Easier to locate specific API calls
Better organization as the app scales

Why `_components/` with underscore?

Signals "private/internal use only"
Prevents accidental reuse of feature-specific components
Keeps module boundaries clear

Why separate `schemas/` and `types/`?

Schemas = Runtime validation (Zod)
Types = Compile-time types (TypeScript)
Often both are needed for the same data structure

🔒 Security Features

✅ HTTP-only cookies for auth tokens
✅ Zod validation on all forms
✅ CSRF protection ready (extend API routes)
✅ Middleware route protection
✅ Type-safe API calls

📚 Learn More

🚀 Deployment

Option 1: Docker Compose (Recommended - Easiest)

1. Create docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - JWT_SECRET=${JWT_SECRET}
      - NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
    restart: unless-stopped

2. Create .env file:

JWT_SECRET=your-secret-key
NEXT_PUBLIC_API_URL=http://localhost:3000/api

3. Run:

docker-compose up -d
docker-compose logs -f  # View logs
docker-compose down     # Stop

Option 2: Docker CLI (Manual Method)

If you prefer more control or don't want to use Docker Compose:

Build the image:

docker build -t nextjs-template .

Run the container:

# Basic
docker run -p 3000:3000 nextjs-template

# With environment file
docker run -p 3000:3000 --env-file .env nextjs-template

# Background mode
docker run -d -p 3000:3000 --name my-app nextjs-template
docker logs -f my-app

Option 3: VPS Deployment (Ubuntu/Debian)

Install dependencies:

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
sudo npm install -g pnpm

# Install PM2 for process management
sudo npm install -g pm2

Clone and setup:

git clone <your-repo-url>
cd nextjs-template
pnpm install

Configure environment:

cp .env.example .env
nano .env  # Edit with your values

Build the application:

pnpm build

Start with PM2:

pm2 start npm --name "nextjs-template" -- start
pm2 save
pm2 startup  # Follow the instructions to enable startup on boot

Setup Nginx reverse proxy:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable site and reload Nginx:

sudo ln -s /etc/nginx/sites-available/nextjs-template /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Setup SSL with Certbot (optional):

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Environment Variables

Make sure to set these in your deployment environment. See .env.example for the complete list of required variables.

Monitoring and Logs

With PM2:

pm2 logs nextjs-template     # View logs
pm2 status                    # Check status
pm2 restart nextjs-template   # Restart app

With Docker:

docker logs -f <container-id>
docker stats

📝 License

MIT

Name		Name	Last commit message	Last commit date
public		public
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
README.md		README.md
components.json		components.json
docker-compose.yml		docker-compose.yml
dockerfile		dockerfile
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation