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
- **Commitizen** for conventional commits
- **Gitea Actions** CI/CD pipeline

## 📁 Project Structure

```treeview
├── .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:**

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

2. **Install dependencies:**

   ```bash
   bun install
   ```

3. **Set up Git hooks:**

   ```bash
   bun run prepare
   ```

4. **Start the development server:**
   ```bash
   bun run dev
   ```

Open [http://localhost:3000](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

2. **Security Audit:**

   - Dependency vulnerability scanning
   - Security audit reporting

## 📊 Code Quality

### Pre-commit Hooks

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

### Conventional Commits

Use `bun run commit` to create conventional commits:

- `feat`: New features
- `fix`: Bug fixes
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Test changes
- `chore`: Maintenance tasks

### 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:

```bash
# 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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- [Next.js Documentation](https://nextjs.org/docs)
- [Bun Documentation](https://bun.sh/docs)
- [TypeScript Documentation](https://www.typescriptlang.org/docs)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [Jest Documentation](https://jestjs.io/docs/getting-started)
- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro)
- [Gitea Documentation](https://docs.gitea.io/)

---

**Happy coding! 🎉**