Next-Template-App-Router/README.md

Next.js Template with App Router

A comprehensive, production-ready Next.js template featuring modern development tools, strict linting, testing setup, and CI/CD pipeline.

🚀 Features

• Next.js 15 with App Router
• TypeScript with strict configuration
• Tailwind CSS for styling
• ESLint with comprehensive rules
• Prettier for code formatting
• Husky for Git hooks
• lint-staged for pre-commit checks
• Jest and React Testing Library for testing
• Gitea Actions CI/CD pipeline

📁 Project Structure

├── .gitea/
│   └── workflows/           # Gitea Actions CI/CD
├── src/
│   ├── app/                # Next.js App Router pages
│   ├── components/         # Reusable React components
│   ├── hooks/              # Custom React hooks
│   ├── lib/                # Utility libraries
│   ├── types/              # TypeScript type definitions
│   └── utils/              # Utility functions
├── public/                 # Static assets
├── __tests__/              # Test files
├── .eslintrc.js           # ESLint configuration
├── .prettierrc.json       # Prettier configuration
├── jest.config.js         # Jest configuration
└── tsconfig.json          # TypeScript configuration

🛠️ Getting Started

Prerequisites

• Bun (latest version recommended)
• Node.js 18.x or higher (for compatibility)

Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd next-template-app-router
   

2. Install dependencies:

   bun install
   

3. Set up Git hooks:

   bun run prepare
   

4. Start the development server:

   bun run dev
   

Open http://localhost:3000 to view the application.

📝 Available Scripts

Script	Description
bun run dev	Start development server with Turbopack
bun run build	Build the application for production
bun run start	Start the production server
bun run lint	Run ESLint
bun run lint:fix	Run ESLint and fix issues
bun run format	Format code with Prettier
bun run format:check	Check code formatting
bun run type-check	Run TypeScript type checking
bun run test	Run tests
bun run test:watch	Run tests in watch mode
bun run test:ci	Run tests for CI
bun run commit	Make a conventional commit

🔧 Configuration

ESLint

The project uses a comprehensive ESLint configuration with:

• Next.js specific rules
• TypeScript support
• React and React Hooks rules
• Import sorting and organization
• Accessibility rules
• Testing library rules

Prettier

Code formatting is handled by Prettier with:

• Consistent code style
• Tailwind CSS class sorting
• TypeScript support

TypeScript

Strict TypeScript configuration with:

• Strict mode enabled
• No unchecked indexed access
• Exact optional property types
• Path mapping for clean imports

Testing

Testing setup includes:

• Jest for unit testing
• React Testing Library for component testing
• Coverage reporting
• Mock utilities for common browser APIs

🔄 CI/CD Pipeline

The Gitea Actions workflow includes:

1. Lint and Test Job:

   • Type checking
   • ESLint validation
   • Prettier formatting check
   • Unit tests with coverage
   • Build verification

📊 Code Quality

Pre-commit Hooks

• ESLint: Catches code issues
• Prettier: Ensures consistent formatting
• Type checking: Validates TypeScript

Coverage Requirements

• Minimum 70% coverage for branches, functions, lines, and statements
• Coverage reports are generated in CI/CD

🎨 Customization

Path Aliases

The project includes TypeScript path aliases:

• @/* → ./src/*
• @/components/* → ./src/components/*
• @/lib/* → ./src/lib/*
• @/utils/* → ./src/utils/*
• @/hooks/* → ./src/hooks/*
• @/types/* → ./src/types/*

Environment Variables

Create a .env.local file for local environment variables:

# Example environment variables
NEXT_PUBLIC_APP_URL=http://localhost:3000
DATABASE_URL=your-database-url

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Run tests: bun test
5. Commit changes: bun run commit
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

🔗 Links

• Next.js Documentation
• Bun Documentation
• TypeScript Documentation
• Tailwind CSS Documentation
• Jest Documentation
• React Testing Library
• Gitea Documentation

---

Happy coding! 🎉