Next.js TypeScript Boilerplate

A modern, production-ready boilerplate for Next.js applications with TypeScript, Tailwind CSS, and essential tooling.

Features

• ⚡ Next.js 15 with App Router
• 🔒 Authentication system with protected routes
• 🎨 Tailwind CSS for styling
• 📝 TypeScript for type safety
• ✅ Jest and React Testing Library for testing
• 🔍 ESLint and Prettier for code quality
• 🪝 Husky and lint-staged for Git hooks
• 🚨 Error Boundary for error handling
• 🔄 API Client with type-safe requests
• 📱 Responsive layout and components

Getting Started

Prerequisites

• Node.js 18+ and npm

Installation

1. Clone the repository:

git clone https://github.com/yourusername/nextjs-boilerplate.git
cd nextjs-boilerplate

2. Install dependencies:

npm install

3. Create a .env.local file:

NEXT_PUBLIC_API_URL=your_api_url

4. Start the development server:

npm run dev

Visit http://localhost:3000 to see your application.

Project Structure

├── src/
│   ├── app/                   # App router pages
│   │   ├── (auth)/           # Authentication routes
│   │   └── (dashboard)/      # Protected dashboard routes
│   ├── components/           # React components
│   │   ├── forms/           # Form components
│   │   ├── layout/          # Layout components
│   │   └── ui/             # UI components
│   ├── hooks/              # Custom React hooks
│   ├── lib/               # Utility functions
│   │   ├── api/          # API client
│   │   └── auth/         # Authentication context
│   └── types/            # TypeScript types
├── public/              # Static files
├── tests/              # Test files
└── package.json

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint errors
• npm run prettier - Format code
• npm run test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage
• npm run type-check - Check TypeScript types

Authentication

The boilerplate includes a complete authentication system with:

• Login and Register pages
• Protected routes middleware
• Authentication context
• Persistent sessions
• Type-safe API integration

Protected Routes

Protected routes are automatically handled by the middleware. Add routes to the protectedPaths array in src/middleware.ts to make them require authentication.

Testing

Tests are set up with Jest and React Testing Library. Example test:

import { render, screen } from '@testing-library/react'
import { HomePage } from '@/app/page'

describe('HomePage', () => {
  it('renders welcome message', () => {
    render(<HomePage />)
    expect(screen.getByText('Welcome')).toBeInTheDocument()
  })
})

API Integration

The boilerplate includes a type-safe API client with:

• Automatic error handling
• TypeScript types for requests and responses
• Authentication header handling
• Request/response interceptors

Example usage:

import { api } from '@/lib/api/fetcher'

// Type-safe API calls
const data = await api.get<UserResponse>('/users')
const user = await api.post<User>('/users', { name: 'John' })

Error Handling

Global error handling is implemented using:

• React Error Boundary
• API error interceptors
• Type-safe error responses

Code Quality

• ESLint with Next.js config
• Prettier for code formatting
• Husky for pre-commit hooks
• lint-staged for staged files

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.