template-nextjs-ts — Next.js 文档模板

SHA-256: b2571bd4ad6b8b356af679f62e90034e14fea4756856a7d72941f6f41c0f50eb

2026-10-14T07:22:50.084Z

# 🚀 Next.js Full-Stack Template

A production-ready Next.js 16+ full-stack template with TypeScript, MongoDB, Tailwind CSS v4, and comprehensive tooling. Features auto-generated OpenAPI documentation, type-safe API client, React Query integration, dark mode support, custom UI components with Framer Motion, form validation with Zod, and complete developer experience.

## ✨ Features

### 🎯 **Dynamic OpenAPI System**

- **Zod-Based Schemas**: Use Zod for validation with built-in OpenAPI metadata
- **Functional Registry**: Declarative route registration with `@asteasolutions/zod-to-openapi`
- **Type-Safe SDK**: Auto-generated React Query hooks with Orval
- **Zero Decorators**: Clean, functional patterns without class decorators
- **Live Documentation**: Interactive Swagger UI at `/api/docs`
- **Full Type Safety**: End-to-end TypeScript with Zod inference

### 🗃️ **MongoDB Integration**

- **Mongoose ODM**: Full MongoDB integration with schema validation
- **Connection Caching**: Optimized for serverless environments
- **Middleware Pattern**: `withDatabase` wrapper for seamless DB connections
- **Model Organization**: Clean separation of concerns with organized models

### 🎨 **Frontend Components**

- **Modern UI Library**: Comprehensive component system with Tailwind CSS v4
- **Dark Mode Support**: Built-in theme switching with CSS custom properties
- **Framer Motion**: Smooth animations and page transitions
- **Form Validation**: Type-safe forms with react-hook-form + Zod
- **State Management**: React Query for server state, React hooks for client state

### 🔧 **Developer Experience**

- **Hot Reload**: Watch mode for automatic OpenAPI regeneration
- **Type Safety**: Full TypeScript support with strict type checking
- **Route-Centric**: Co-located types and endpoints for better maintainability
- **Modern Stack**: Next.js 16+ App Router with ES modules

## 🚀 Quick Start

### Prerequisites

- Node.js 18+
- MongoDB Atlas account or local MongoDB instance
- npm or yarn

### Installation

```bash
# Clone the template
git clone https://github.com/YousifAbozid/template-nextjs-ts.git
cd template-nextjs-ts

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your MongoDB connection string

# Generate API documentation and SDK
npm run api:generate
npm run api:sdk

# Start development server
npm run dev
```

### Environment Variables

```bash
# .env
MONGODB_URI=mongodb+srv://username:[email protected]/database
API_TITLE="Your API Title"
API_VERSION="1.0.0"
API_DESCRIPTION="Your API Description"
```

## 📁 Project Structure

```
app/
├── api/                    # 🟢 API Routes (You modify these)
│   ├── users/
│   │   ├── route.ts       # API endpoints (GET, POST, etc.)
│   │   ├── schema.ts      # Zod schemas for validation + OpenAPI
│   │   └── openapi.ts     # OpenAPI route registration
│   ├── health/            # Health check endpoint
│   ├── docs/              # Swagger UI documentation
│   └── openapi.json/      # OpenAPI specification endpoint
├── components/            # 🟢 React components
│   ├── ui/                # Base UI components (Button, Card, etc.)
│   └── shared/            # Shared business components
├── context/               # 🟢 React context providers
│   ├── Providers.tsx      # App-level providers
│   ├── ThemeProvider.tsx  # Dark/light mode
│   └── ToastContext.tsx   # Toast notifications
├── lib/                   # Shared utilities and business logic
│   ├── api/
│   │   ├── database/      # 🟢 Database connection utilities
│   │   ├── middleware/    # 🟢 Custom middleware
│   │   ├── models/        # 🟢 Mongoose models
│   │   ├── openapi/       # 🟢 OpenAPI registry and helpers
│   │   ├── config.ts      # 🟡 API configuration
│   │   └── sdk-mutator.ts # 🟡 Orval custom fetch instance
│   └── network/           # 🟢 React Query configuration
├── layout.tsx             # Root layout with providers
├── page.tsx               # Landing page with component showcase
└── globals.css            # Global styles with CSS custom properties
```

**Legend**: 🟢 Safe to modify | 🟡 Modify carefully | 🔴 Auto-generated (don't touch)

## 🎯 Adding New API Routes

### 1. Create Route Structure

```bash
mkdir app/api/products
touch app/api/products/route.ts app/api/products/schema.ts app/api/products/openapi.ts
```

### 2. Define Schemas (`schema.ts`)

```typescript
import { z } from 'zod';
import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';

extendZodWithOpenApi(z);

export const CreateProductRequestSchema = z
  .object({
    name: z
      .string()
      .min(1)
      .openapi({ description: 'Product name', example: 'Widget' }),
    price: z
      .number()
      .min(0)
      .openapi({ description: 'Price in USD', example: 29.99 }),
    category: z
      .string()
      .openapi({ description: 'Product category', example: 'Electronics' }),
    description: z
      .string()
      .optional()
      .openapi({ description: 'Product description' })
  })
  .openapi('CreateProductRequest');

export const ProductSchema = z
  .object({
    _id: z.string().openapi({ example: '507f1f77bcf86cd799439011' }),
    name: z.string(),
    price: z.number(),
    category: z.string(),
    description: z.string().optional(),
    createdAt: z.coerce.date(),
    updatedAt: z.coerce.date()
  })
  .openapi('Product');

export type CreateProductRequest = z.infer<typeof CreateProductRequestSchema>;
export type Product = z.infer<typeof ProductSchema>;
```

### 3. Register OpenAPI Routes (`openapi.ts`)

```typescript
import {
  registry,
  createRouteConfig,
  createListResponse
} from '@/lib/api/openapi';
import { CreateProductRequestSchema, ProductSchema } from './schema';

// GET /api/products
registry.registerPath(
  createRouteConfig({
    method: 'get',
    path: '/api/products',
    tags: ['Products'],
    summary: 'Get all products',
    responses: {
      200: {
        description: 'List of products',
        content: {
          'application/json': {
            schema: createListResponse(ProductSchema)
          }
        }
      }
    }
  })
);

// POST /api/products
registry.registerPath(
  createRouteConfig({
    method: 'post',
    path: '/api/products',
    tags: ['Products'],
    summary: 'Create a new product',
    request: {
      body: {
        content: {
          'application/json': {
            schema: CreateProductRequestSchema
          }
        }
      }
    },
    responses: {
      201: {
        description: 'Product created successfully',
        content: {
          'application/json': {
            schema: z.object({
              success: z.literal(true),
              data: ProductSchema,
              message: z.string()
            })
          }
        }
      }
    }
  })
);
```

### 4. Create Route Handler (`route.ts`)

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { withDatabase } from '@/lib/api/middleware';
import { Product } from '@/lib/api/models';
import { CreateProductRequestSchema } from './schema';
import './openapi'; // ⚠️ CRITICAL: Import to register OpenAPI routes

export const GET = withDatabase(async () => {
  const products = await Product.find().sort({ createdAt: -1 });
  return NextResponse.json({
    success: true,
    data: products,
    count: products.length
  });
});

export const POST = withDatabase(async (req: NextRequest) => {
  try {
    const body = await req.json();

    // Validate with Zod
    const validationResult = CreateProductRequestSchema.safeParse(body);
    if (!validationResult.success) {
      return NextResponse.json(
        { success: false, error: validationResult.error.errors[0].message },
        { status: 400 }
      );
    }

    const product = new Product(validationResult.data);
    const savedProduct = await product.save();

    return NextResponse.json(
      {
        success: true,
        data: savedProduct,
        message: 'Product created successfully'
      },
      { status: 201 }
    );
  } catch (error) {
    console.error('Create product error:', error);
    return NextResponse.json(
      { success: false, error: 'Failed to create product' },
      { status: 500 }
    );
  }
});
```

### 5. Create Database Model (`app/lib/api/models/Product.ts`)

```typescript
import mongoose, { Schema, Document } from 'mongoose';

export interface IProduct extends Document {
  name: string;
  price: number;
  category: string;
  description?: string;
  createdAt: Date;
  updatedAt: Date;
}

const ProductSchema: Schema<IProduct> = new Schema(
  {
    name: { type: String, required: true, trim: true },
    price: { type: Number, required: true, min: 0 },
    category: { type: String, required: true, trim: true },
    description: { type: String, trim: true }
  },
  { timestamps: true }
);

export const Product =
  mongoose.models.Product || mongoose.model<IProduct>('Product', ProductSchema);
```

### 6. Generate Documentation and SDK

```bash
npm run api:generate  # Generate OpenAPI spec
npm run api:sdk       # Generate React Query SDK
```

**Result**: Your new route automatically appears in:

- OpenAPI spec at `/api/openapi.json`
- Interactive docs at `/api/docs`
- Generated React Query hooks in `sdk/index.ts`

## 🎨 Frontend Development

### Using UI Components

```typescript
import { Button } from '@/components/ui/Button';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/Card';
import { useToast } from '@/context/ToastContext';

export function ExampleComponent() {
  const { showToast } = useToast();

  return (
    <Card>
      <CardHeader>
        <CardTitle>Example Component</CardTitle>
      </CardHeader>
      <CardContent>
        <Button
          onClick={() => showToast('Success!', 'success')}
          variant="default"
        >
          Click me
        </Button>
      </CardContent>
    </Card>
  );
}
```

### API Integration with Generated SDK

```typescript
import { useGetApiUsers, usePostApiUsers } from 'sdk';

// Using auto-generated React Query hooks
export function UsersList() {
  const { data: response, isLoading } = useGetApiUsers();
  const createUser = usePostApiUsers();

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {response?.data?.map(user => (
        <div key={user._id}>{user.name}</div>
      ))}
      <button
        onClick={() => createUser.mutate({ data: { name: 'John', email: '[email protected]' } })}
      >
        Add User
      </button>
    </div>
  );
}
```

## 🔧 Available Scripts

```bash
npm run dev              # Start development server
npm run build            # Build for production (includes OpenAPI + SDK generation)
npm run start            # Start production server
npm run api:generate     # Generate OpenAPI spec from route definitions
npm run api:sdk          # Generate React Query SDK with Orval
npm run api:watch        # Watch mode: OpenAPI + SDK auto-regeneration
npm run api:dev          # Start dev server + watch OpenAPI + SDK
npm run type-check       # TypeScript type checking
npm run lint             # ESLint
npm run lint:fix         # ESLint with auto-fix
npm run format           # Prettier formatting
npm run test             # Run all checks (format, lint, type-check)
```

## 📖 API Documentation

Once running, access your documentation and app:

- **Frontend App**: [http://localhost:3000](http://localhost:3000) (Landing page with component showcase)
- **Interactive Docs**: [http://localhost:3000/api/docs](http://localhost:3000/api/docs)
- **OpenAPI Spec**: [http://localhost:3000/api/openapi.json](http://localhost:3000/api/openapi.json)
- **Health Check**: [http://localhost:3000/api/health](http://localhost:3000/api/health)

## 🔄 Auto-Generation Workflow

The system uses a two-step generation process:

1. **OpenAPI Generation**: Imports all `openapi.ts` files to build the OpenAPI spec
2. **SDK Generation**: Uses Orval to generate React Query hooks from the spec

### How It Works:

1. Define **Zod schemas** in `schema.ts` with `.openapi()` metadata
2. Register routes in `openapi.ts` using `registry.registerPath()`
3. Import `'./openapi'` in `route.ts` to trigger registration
4. Run `npm run api:generate` to build `openapi.json`
5. Run `npm run api:sdk` to generate React Query hooks in `sdk/`

### Generated Files (Auto-updated)

- `openapi.json` - OpenAPI 3.0 specification (project root)
- `sdk/index.ts` - Type-safe React Query hooks and types

## 🛠️ Tech Stack

### Frontend

- **Framework**: [Next.js 16+](https://nextjs.org/) (App Router) + [React 19](https://react.dev/)
- **Styling**: [Tailwind CSS v4](https://tailwindcss.com/) with CSS custom properties
- **Components**: Custom UI library with [Framer Motion](https://www.framer.com/motion/)
- **State Management**: [React Query](https://tanstack.com/query) + React hooks
- **Forms**: [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/)
- **Icons**: [Lucide React](https://lucide.dev/)

### Backend

- **Language**: TypeScript with ES Modules
- **Database**: [MongoDB](https://www.mongodb.com/) with [Mongoose](https://mongoosejs.com/)
- **Validation**: [Zod](https://zod.dev/) schemas with OpenAPI extensions
- **Documentation**: [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3) + [Swagger UI](https://swagger.io/tools/swagger-ui/)
- **SDK Generation**: [Orval](https://orval.dev/) for React Query hooks
- **OpenAPI Tools**: [@asteasolutions/zod-to-openapi](https://github.com/asteasolutions/zod-to-openapi)

### Developer Tools

- **Code Quality**: [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) + [TypeScript](https://www.typescriptlang.org/)
- **Git Hooks**: [Husky](https://typicode.github.io/husky/) + [lint-staged](https://github.com/okonet/lint-staged)
- **Development**: [Chokidar](https://github.com/paulmillr/chokidar) file watching + [Concurrently](https://github.com/open-cli-tools/concurrently)

## 🚀 Deployment

### Vercel (Recommended)

```bash
# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod
```

### Docker

```bash
# Build image
docker build -t nextjs-backend .

# Run container
docker run -p 3000:3000 nextjs-backend
```

### Manual Deployment

```bash
# Build for production
npm run build

# Start production server
npm start
```

## 📚 Additional Resources

- **[Backend Development Guide](app/BACKEND_DEVELOPMENT_GUIDE.md)** - Comprehensive backend documentation
- **[SDK Usage Examples](SDK_USAGE_EXAMPLES.md)** - Frontend integration with React Query
- **[Middleware Guide](MIDDLEWARE_GUIDE.md)** - Understanding Next.js proxy vs route middleware
- **[GitHub Copilot Instructions](.github/copilot-instructions.md)** - AI coding assistant setup

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

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

## 🙏 Acknowledgments

- [Next.js](https://nextjs.org/) team for the amazing framework
- [Mongoose](https://mongoosejs.com/) for MongoDB integration
- [OpenAPI](https://www.openapis.org/) specification contributors
- [Swagger](https://swagger.io/) for API documentation tools

---

**Built with ❤️ by [Yousif Abozid](https://github.com/YousifAbozid)**