前端+AI工程模板
一个生产就绪的Next.js 15模板，具有多提供商AI集成、Jotai状态管理和MCP工具架构。
特性
- Next.js 15 使用App Router和Turbopack
- 多提供商AI -Google Gemini和OpenAI支持回退
- 佐敦州管理 -原子性、可扩展的状态，无需样板
- MCP工具 -AI工具编排的模型上下文协议
- TypeScript -具有全面类型定义的严格模式
- Tailwind CSS -实用性优先，响应式设计
- 测试 -Vitest用于单元测试，剧作家用于E2E
- 代码质量 -ESLint、Lefthok、Commitline
快速开始
# Clone the template
npx degit cheshirecode/frontend-ai-template my-ai-app
cd my-ai-app
# Install dependencies
npm install
# Set up environment
cp .env.example .env.local
# Add your API keys to .env.local
# Start development server
npm run dev打开 http://localhost:3000 查看您的应用程序。
环境设置
至少需要一个AI提供商API密钥：
| 变量 | 描述 | 必填 |
|---|---|---|
GOOGLE_GENERATIVE_AI_API_KEY | Google Gemini API密钥 | 其中之一 |
OPENAI_API_KEY | 需要OpenAI API密钥 | |
AI_DEFAULT_PROVIDER | 默认提供程序（gemini/openai） | 否 |
拿到你的钥匙：
项目结构
├── app/
│ ├── api/
│ │ ├── ai/ # AI chat endpoint
│ │ └── mcp/ # MCP tools endpoint
│ │ └── tools/ # Tool definitions
│ ├── components/
│ │ ├── chat/ # Chat UI components
│ │ ├── common/ # Shared components
│ │ ├── layout/ # Layout components
│ │ └── providers/ # React providers
│ ├── hooks/
│ │ ├── chat/ # Chat hooks
│ │ ├── composed/ # High-level hooks
│ │ └── core/ # Core state hooks
│ ├── lib/
│ │ ├── ai-service.ts # AI provider abstraction
│ │ ├── error-handler.ts # Error utilities
│ │ └── logger.ts # Structured logging
│ └── store/ # Jotai atoms
├── types/ # TypeScript definitions
├── e2e/ # Playwright tests
└── docs/ # Documentation可用脚本
npm run dev # Start dev server with Turbopack
npm run build # Production build
npm run start # Start production server
npm test # Run unit tests
npm run test:e2e # Run E2E tests
npm run lint # Lint code
npm run type-check # TypeScript check定制
添加AI工具
在中创建新工具 app/api/mcp/tools/:
// app/api/mcp/tools/my-tool.ts
import { MCPTool, MCPToolResult, ToolHandler } from './types'
export const myTool: MCPTool = {
name: 'my_tool',
description: 'Description of what the tool does',
inputSchema: {
type: 'object',
properties: {
input: { type: 'string', description: 'Input parameter' }
},
required: ['input']
}
}
export const handleMyTool: ToolHandler = async (params) => {
// Implementation
return { success: true, data: result }
}注册于 app/api/mcp/tools/index.ts.
添加组件
组件遵循分解模式：
// app/components/feature/MyComponent.tsx
'use client'
import { useMyHook } from '@/hooks/feature/useMyHook'
interface MyComponentProps {
title: string
}
export function MyComponent({ title }: MyComponentProps) {
const { data, isLoading } = useMyHook()
// ...
}添加州
使用Jotai原子 app/store/:
import { atom } from 'jotai'
export const myAtom = atom('')
export const derivedAtom = atom((get) => get(myAtom).toUpperCase())建筑
看 docs/ARCHITECTURE.md 获取详细的架构文档。
部署
Vercel（推荐）
npm run deploy:vercel其他平台
构建并运行生产服务器：
npm run build
npm run start贡献
- 克隆该仓库
- 创建要素分支
- 进行更改
- 运行测试：
npm test && npm run test:e2e - 提交拉取请求
许可证
麻省理工学院