Back to Details

nextjs-project-starter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Next.js Project Starter

Next.js 项目启动器

Create new Next.js projects with a configurable stack, always using latest stable versions with documentation verification.
创建具备可配置技术栈的全新Next.js项目，始终使用经过文档验证的最新稳定版本。

When to Use

使用场景

  • Creating a new personal project
  • Starting a fullstack Next.js application
  • Bootstrapping a project with Mantine + Supabase stack
  • User says "create new project", "start new app", "nuevo proyecto"
  • 创建新的个人项目
  • 启动全栈Next.js应用
  • 基于Mantine + Supabase技术栈初始化项目
  • 用户说出“创建新项目”、“启动新应用”、“nuevo proyecto”（西班牙语：新项目）时

Core Principles

核心原则

  1. Always ask before acting - Never assume, always confirm
  2. Latest versions - Search npm/docs for current stable versions
  3. Show breaking changes - Warn about major version changes
  4. Configurable - Let user choose what to include
  1. 操作前务必确认 - 绝不假设，始终先确认
  2. 使用最新版本 - 在npm/官方文档中查找当前稳定版本
  3. 提示重大变更 - 警告主要版本更新带来的破坏性变更
  4. 可配置化 - 让用户选择要包含的功能

Workflow

工作流程

Phase 1: Project Basics

阶段1：项目基础信息

Ask user for:
1. Project name (kebab-case)
2. Project description (one line)
3. Target domain (carlosmonti.com / xmontc.xyz / custom / none)
向用户询问：
1. 项目名称（短横线分隔格式，kebab-case）
2. 项目描述（一句话）
3. 目标域名（carlosmonti.com / xmontc.xyz / 自定义 / 无）

Phase 2: Node Version Setup

阶段2：Node版本设置

bash
undefined
bash
undefined

Check current node version

检查当前Node版本

nvm current
nvm current

Search for Next.js recommended Node version

查找Next.js推荐的Node版本

(use WebSearch to find latest compatibility)

（使用WebSearch获取最新兼容性信息）


Present options:
Node.js version for this project: ☐ Use current (vX.X.X) ☐ Use Next.js recommended LTS (vX.X.X) ☐ Specify custom version

Generate:
- `.nvmrc` with selected version
- `package.json` with `"engines": { "node": ">=X.X.X" }`

提供选项：
本项目使用的Node.js版本： ☐ 使用当前版本 (vX.X.X) ☐ 使用Next.js推荐的LTS版本 (vX.X.X) ☐ 指定自定义版本

生成文件：
- 包含选定版本的 `.nvmrc`
- 带有 `"engines": { "node": ">=X.X.X" }` 的 `package.json`

Phase 3: Feature Selection

阶段3：功能选择

Present configurable features:
Core Features (select all that apply):
☐ Mantine UI + Tabler Icons
☐ Supabase (auth + database)
☐ Zustand (state management)
☐ Zod (validation)
☐ SWR (data fetching)
☐ TanStack Query (alternative to SWR)
☐ Vercel Analytics + Speed Insights
☐ Testing setup (Vitest + Testing Library)
提供可配置的功能选项：
核心功能（可多选）：
☐ Mantine UI + Tabler Icons
☐ Supabase（认证 + 数据库）
☐ Zustand（状态管理）
☐ Zod（校验工具）
☐ SWR（数据获取）
☐ TanStack Query（SWR的替代方案）
☐ Vercel Analytics + Speed Insights
☐ 测试环境搭建（Vitest + Testing Library）

Phase 4: Version & Docs Verification

阶段4：版本与文档验证

For EACH selected feature, execute this process:
bash
undefined
对于每个选定的功能，执行以下流程：
bash
undefined

1. Get latest version

1. 获取最新版本

npm view @mantine/core version
npm view @mantine/core version

2. Search for documentation and breaking changes

2. 查找文档与破坏性变更

Use WebSearch or Exa to find:

使用WebSearch或Exa查找：

- Official docs

- 官方文档

- Migration guides

- 迁移指南

- Known issues

- 已知问题


Present to user:
📦 @mantine/core Version: ^7.15.0 (latest stable) Docs: https://mantine.dev/getting-started ⚠️ Note: v7 requires PostCSS preset (breaking from v6)
Install this version? [Y/n]

**IMPORTANT**: Do this for EACH dependency before installing. Never batch install without verification.

向用户展示：
📦 @mantine/core 版本：^7.15.0（最新稳定版） 文档：https://mantine.dev/getting-started ⚠️ 注意：v7版本需要PostCSS预设（与v6版本不兼容）
是否安装此版本？ [Y/n]

**重要提示**：安装前务必对每个依赖执行此步骤。绝不要未经验证就批量安装依赖。

Phase 5: Integration Questions

阶段5：集成配置询问

After features are confirmed, ask about integrations:
Project Integrations (confirm each):

1. GitHub Repository
   ☐ Create private repo on GitHub?
   → Will use: gh repo create {name} --private

2. Vercel Deployment
   ☐ Link to Vercel for auto-deploy?
   → Will use: vercel link

3. Supabase Project (if Supabase selected)
   ☐ Create new Supabase project?
   → Will guide through supabase.com setup

4. CLAUDE.md
   ☐ Generate CLAUDE.md for this project?
   → Will create based on selected stack
功能确认后，询问集成相关配置：
项目集成配置（逐一确认）：

1. GitHub仓库
   ☐ 在GitHub上创建私有仓库？
   → 将执行：gh repo create {name} --private

2. Vercel部署
   ☐ 关联Vercel以实现自动部署？
   → 将执行：vercel link

3. Supabase项目（若已选择Supabase）
   ☐ 创建新的Supabase项目？
   → 将引导完成supabase.com上的设置流程

4. CLAUDE.md
   ☐ 为该项目生成CLAUDE.md文档？
   → 将基于选定的技术栈创建文档

Phase 6: Project Creation

阶段6：项目创建

Execute in order:
bash
undefined
按顺序执行以下命令：
bash
undefined

1. Create Next.js project

1. 创建Next.js项目

npx create-next-app@latest {project-name}
--typescript
--eslint
--app
--src-dir
--import-alias "@/*"
npx create-next-app@latest {project-name}
--typescript
--eslint
--app
--src-dir
--import-alias "@/*"

2. Navigate to project

2. 进入项目目录

cd {project-name}
cd {project-name}

3. Create .nvmrc

3. 创建.nvmrc文件

echo "{node-version}" > .nvmrc
echo "{node-version}" > .nvmrc

4. Install selected dependencies (with verified versions)

4. 安装选定的依赖（使用已验证的版本）

npm install @mantine/core@^{version} @mantine/hooks@^{version} ...
undefined
npm install @mantine/core@^{version} @mantine/hooks@^{version} ...
undefined

Phase 7: Structure Generation

阶段7：目录结构生成

Create preferred folder structure:
src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   ├── (auth)/            # Auth route group
│   └── (main)/            # Main app routes
├── components/            # React components
│   ├── ui/               # Base UI components
│   └── features/         # Feature-specific components
├── hooks/                 # Custom React hooks
├── lib/                   # Core utilities
├── providers/             # React context providers
├── stores/                # Zustand stores
├── types/                 # TypeScript types
├── utils/                 # Utility functions
│   └── supabase/         # Supabase client (if selected)
└── test/                  # Test setup & mocks
    ├── mocks/
    └── setup/
创建推荐的目录结构：
src/
├── app/                    # Next.js App Router
│   ├── api/               # API路由
│   ├── (auth)/            # 认证路由组
│   └── (main)/            # 主应用路由
├── components/            # React组件
│   ├── ui/               # 基础UI组件
│   └── features/         # 功能特定组件
├── hooks/                 # 自定义React Hooks
├── lib/                   # 核心工具库
├── providers/             # React上下文提供者
├── stores/                # Zustand状态仓库
├── types/                 # TypeScript类型定义
├── utils/                 # 工具函数
│   └── supabase/         # Supabase客户端（若已选择）
└── test/                  # 测试环境配置与模拟数据
    ├── mocks/
    └── setup/

Phase 8: Configuration Files

阶段8：配置文件生成

Generate based on selections:
根据用户选择生成配置文件：

If Mantine selected:

若选择了Mantine：

javascript
// postcss.config.mjs
export default {
  plugins: {
    'postcss-preset-mantine': {},
    'postcss-simple-vars': {
      variables: {
        'mantine-breakpoint-xs': '36em',
        'mantine-breakpoint-sm': '48em',
        'mantine-breakpoint-md': '62em',
        'mantine-breakpoint-lg': '75em',
        'mantine-breakpoint-xl': '88em',
      },
    },
  },
};
javascript
// postcss.config.mjs
export default {
  plugins: {
    'postcss-preset-mantine': {},
    'postcss-simple-vars': {
      variables: {
        'mantine-breakpoint-xs': '36em',
        'mantine-breakpoint-sm': '48em',
        'mantine-breakpoint-md': '62em',
        'mantine-breakpoint-lg': '75em',
        'mantine-breakpoint-xl': '88em',
      },
    },
  },
};

If Supabase selected:

若选择了Supabase：

typescript
// src/utils/supabase/client.ts
// src/utils/supabase/server.ts
// src/utils/supabase/middleware.ts
typescript
// src/utils/supabase/client.ts
// src/utils/supabase/server.ts
// src/utils/supabase/middleware.ts

Environment template:

环境变量模板：

bash
undefined
bash
undefined

.env.example

.env.example

Supabase (if selected)

Supabase（若已选择）

NEXT_PUBLIC_SUPABASE_URL= NEXT_PUBLIC_SUPABASE_ANON_KEY= SUPABASE_SERVICE_ROLE_KEY=
NEXT_PUBLIC_SUPABASE_URL= NEXT_PUBLIC_SUPABASE_ANON_KEY= SUPABASE_SERVICE_ROLE_KEY=

Analytics (if selected)

分析工具（若已选择）

NEXT_PUBLIC_VERCEL_ANALYTICS_ID=
undefined
NEXT_PUBLIC_VERCEL_ANALYTICS_ID=
undefined

Phase 9: CLAUDE.md Generation

阶段9：CLAUDE.md文档生成

If user confirmed, generate CLAUDE.md with:
markdown
undefined
若用户确认，生成CLAUDE.md文档，内容如下：
markdown
undefined

{Project Name}

{项目名称}

{Description}
{项目描述}

Stack

技术栈

  • Framework: Next.js {version} (App Router)
  • UI: Mantine {version}
  • Database: Supabase
  • State: Zustand
  • Validation: Zod
  • 框架: Next.js {版本} (App Router)
  • UI组件库: Mantine {版本}
  • 数据库: Supabase
  • 状态管理: Zustand
  • 校验工具: Zod

Commands

常用命令

bash
npm run dev      # Start development server
npm run build    # Production build
npm run test     # Run tests
npm run lint     # Run ESLint
bash
npm run dev      # 启动开发服务器
npm run build    # 生产环境构建
npm run test     # 运行测试
npm run lint     # 执行ESLint检查

Project Structure

项目结构

{Generated structure tree}
{生成的目录结构树}

Key Patterns

核心模式

  • Server Components by default
  • Client Components marked with 'use client'
  • API routes in src/app/api/
  • Zustand stores in src/stores/
undefined
  • 默认使用Server Components
  • Client Components需标记'use client'
  • API路由位于src/app/api/
  • Zustand状态仓库位于src/stores/
undefined

Phase 10: Final Summary

阶段10：最终总结

Present summary to user:
✅ Project created: {name}

📁 Location: ~/Projects/github/{name}
🔧 Node: {version} (via .nvmrc)

📦 Installed:
   - next@{version}
   - @mantine/core@{version}
   - @supabase/ssr@{version}
   - zustand@{version}
   - zod@{version}

🔗 Integrations:
   - GitHub: https://github.com/testacode/{name}
   - Vercel: Linked (auto-deploy on push)
   - Supabase: {project-url}

📝 Next steps:
   1. cd {name}
   2. cp .env.example .env.local
   3. Configure Supabase credentials
   4. npm run dev
向用户展示项目创建总结：
✅ 项目创建完成: {名称}

📁 位置: ~/Projects/github/{名称}
🔧 Node版本: {版本}（通过.nvmrc配置）

📦 已安装依赖:
   - next@{版本}
   - @mantine/core@{版本}
   - @supabase/ssr@{版本}
   - zustand@{版本}
   - zod@{版本}

🔗 已配置集成:
   - GitHub: https://github.com/testacode/{名称}
   - Vercel: 已关联（推送代码时自动部署）
   - Supabase: {项目地址}

📝 下一步操作:
   1. cd {名称}
   2. cp .env.example .env.local
   3. 配置Supabase凭证
   4. npm run dev

Dependencies Reference

依赖参考

When searching for versions, use these as baseline:
PackagePurposeDocs URL
nextFrameworkhttps://nextjs.org/docs
@mantine/coreUI Componentshttps://mantine.dev
@mantine/hooksReact Hookshttps://mantine.dev/hooks
@tabler/icons-reactIconshttps://tabler.io/icons
@supabase/ssrSupabase SSRhttps://supabase.com/docs
zustandStatehttps://zustand-demo.pmnd.rs
zodValidationhttps://zod.dev
swrData Fetchinghttps://swr.vercel.app
@tanstack/react-queryData Fetchinghttps://tanstack.com/query
vitestTestinghttps://vitest.dev
查找版本时，以下为基准参考：
包名用途文档地址
next开发框架https://nextjs.org/docs
@mantine/coreUI组件库https://mantine.dev
@mantine/hooksReact Hookshttps://mantine.dev/hooks
@tabler/icons-react图标库https://tabler.io/icons
@supabase/ssrSupabase SSR支持https://supabase.com/docs
zustand状态管理https://zustand-demo.pmnd.rs
zod数据校验https://zod.dev
swr数据获取https://swr.vercel.app
@tanstack/react-query数据获取https://tanstack.com/query
vitest测试框架https://vitest.dev

Error Handling

错误处理

If any step fails:
  1. npm install fails: Check Node version, try with 
    --legacy-peer-deps
  2. gh repo create fails: Verify 
    gh auth status
  3. vercel link fails: Run 
    vercel login
    first
  4. Supabase setup fails: Guide user to manual setup at supabase.com
Always ask user how to proceed on errors, never assume.
若任何步骤失败：
  1. npm install失败: 检查Node版本，尝试添加
    --legacy-peer-deps
    参数
  2. gh repo create失败: 验证
    gh auth status
    的认证状态
  3. vercel link失败: 先执行
    vercel login
    登录
  4. Supabase配置失败: 引导用户前往supabase.com手动完成配置
遇到错误时，务必询问用户如何继续，绝不自行假设处理方式。