fullstack-workspace-init
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFull Stack Workspace Init
全栈工作区初始化
Create a production-ready monorepo with working MVP features:
- Frontend: NextJS 16 + React 19 + TypeScript + Tailwind + @agenticindiedev/ui
- Backend: NestJS 11 + MongoDB + Clerk Auth + Swagger
- Mobile: React Native + Expo (optional)
- Quality: Vitest (80% coverage) + Biome + Husky + GitHub Actions CI/CD
- Package Manager: bun
创建一个生产就绪的单体仓库,包含可运行的MVP功能:
- 前端: NextJS 16 + React 19 + TypeScript + Tailwind + @agenticindiedev/ui
- 后端: NestJS 11 + MongoDB + Clerk Auth + Swagger
- 移动端: React Native + Expo(可选)
- 质量保障: Vitest(80%覆盖率) + Biome + Husky + GitHub Actions CI/CD
- 包管理器: bun
What Makes This Different
核心优势
This skill generates working applications, not empty scaffolds:
- Complete CRUD operations for your main entities
- Clerk authentication configured and working
- Tests with 80% coverage threshold
- GitHub Actions CI/CD pipeline
- Runs immediately with
bun dev
该工具生成的是可直接运行的应用,而非空脚手架:
- 为核心业务实体生成完整的CRUD操作
- 已配置并可运行的Clerk身份验证
- 覆盖率达80%的测试用例
- GitHub Actions CI/CD流水线
- 可通过立即启动
bun dev
Workflow
工作流程
Phase 1: PRD Brief Intake
阶段1:需求简报收集
Ask the user for a 1-2 paragraph product description, then extract and confirm:
I'll help you build [Project Name]. Based on your description, I understand:
**Entities:**
- [Entity1]: [fields]
- [Entity2]: [fields]
**Features:**
- [Feature 1]
- [Feature 2]
**Routes:**
- / - Home/Dashboard
- /[entity] - List view
- /[entity]/[id] - Detail view
**API Endpoints:**
- GET/POST /api/[entity]
- GET/PATCH/DELETE /api/[entity]/:id
Is this correct? Any adjustments?向用户收集1-2段的产品描述,然后提取并确认以下内容:
我将帮您构建[项目名称]。根据您的描述,我理解:
**业务实体:**
- [实体1]:[字段]
- [实体2]:[字段]
**功能特性:**
- [功能1]
- [功能2]
**页面路由:**
- / - 首页/仪表盘
- /[entity] - 列表页
- /[entity]/[id] - 详情页
**API接口:**
- GET/POST /api/[entity]
- GET/PATCH/DELETE /api/[entity]/:id
以上内容是否正确?是否需要调整?Phase 2: Auth Setup (Always Included)
阶段2:身份验证配置(默认包含)
Generate Clerk authentication:
Backend:
- - Token verification guard
auth/guards/clerk-auth.guard.ts - - User extraction decorator
auth/decorators/current-user.decorator.ts
Frontend:
- - ClerkProvider wrapper
providers/clerk-provider.tsx - - Sign in page
app/sign-in/[[...sign-in]]/page.tsx - - Sign up page
app/sign-up/[[...sign-up]]/page.tsx - - Protected route middleware
middleware.ts
Environment:
- with all required variables
.env.example
生成Clerk身份验证相关代码:
后端:
- - Token验证守卫
auth/guards/clerk-auth.guard.ts - - 用户信息提取装饰器
auth/decorators/current-user.decorator.ts
前端:
- - ClerkProvider包装组件
providers/clerk-provider.tsx - - 登录页面
app/sign-in/[[...sign-in]]/page.tsx - - 注册页面
app/sign-up/[[...sign-up]]/page.tsx - - 受保护路由中间件
middleware.ts
环境配置:
- 包含所有必需的环境变量
.env.example
Phase 3: Entity Generation
阶段3:业务实体生成
For each extracted entity, generate complete CRUD with tests:
Backend (NestJS):
api/apps/api/src/collections/{entity}/
├── {entity}.module.ts
├── {entity}.controller.ts # Full CRUD + Swagger + ClerkAuthGuard
├── {entity}.controller.spec.ts # Controller unit tests
├── {entity}.service.ts # Business logic
├── {entity}.service.spec.ts # Service unit tests
├── schemas/
│ └── {entity}.schema.ts # Mongoose schema with userId
└── dto/
├── create-{entity}.dto.ts # class-validator decorators
└── update-{entity}.dto.ts # PartialType of create
api/apps/api/test/
├── {entity}.e2e-spec.ts # E2E tests with supertest
└── setup.ts # Test setup with MongoDB Memory ServerFrontend (NextJS):
frontend/apps/dashboard/
├── app/{entity}/
│ ├── page.tsx # List view (protected)
│ └── [id]/page.tsx # Detail view (protected)
├── src/test/
│ └── setup.ts # Test setup with Clerk mocks
└── vitest.config.ts # Frontend test config (jsdom)
frontend/packages/components/
├── {entity}-list.tsx
├── {entity}-list.spec.tsx # Component tests
├── {entity}-form.tsx
├── {entity}-form.spec.tsx # Component tests
└── {entity}-item.tsx
frontend/packages/hooks/
├── use-{entities}.ts # React hook for state management
└── use-{entities}.spec.ts # Hook tests
frontend/packages/services/
└── {entity}.service.ts # API client with auth headers为每个提取的业务实体生成带测试的完整CRUD代码:
后端(NestJS):
api/apps/api/src/collections/{entity}/
├── {entity}.module.ts
├── {entity}.controller.ts # 完整CRUD + Swagger + ClerkAuthGuard
├── {entity}.controller.spec.ts # 控制器单元测试
├── {entity}.service.ts # 业务逻辑层
├── {entity}.service.spec.ts # 服务层单元测试
├── schemas/
│ └── {entity}.schema.ts # 关联userId的Mongoose Schema
└── dto/
├── create-{entity}.dto.ts # 带有class-validator装饰器的DTO
└── update-{entity}.dto.ts # 基于create DTO的PartialType
api/apps/api/test/
├── {entity}.e2e-spec.ts # 使用supertest的E2E测试
└── setup.ts # 基于MongoDB Memory Server的测试配置前端(NextJS):
frontend/apps/dashboard/
├── app/{entity}/
│ ├── page.tsx # 受保护的列表页
│ └── [id]/page.tsx # 受保护的详情页
├── src/test/
│ └── setup.ts # 带有Clerk模拟的测试配置
└── vitest.config.ts # 前端测试配置(jsdom)
frontend/packages/components/
├── {entity}-list.tsx
├── {entity}-list.spec.tsx # 组件测试
├── {entity}-form.tsx
├── {entity}-form.spec.tsx # 组件测试
└── {entity}-item.tsx
frontend/packages/hooks/
├── use-{entities}.ts # React状态管理Hook
└── use-{entities}.spec.ts # Hook测试
frontend/packages/services/
└── {entity}.service.ts # 带有认证头的API客户端Phase 4: Quality Setup
阶段4:质量保障配置
Vitest Configuration:
- in each project
vitest.config.ts - 80% coverage threshold for lines, functions, branches
- provider
@vitest/coverage-v8
GitHub Actions:
.github/workflows/ci.yml- Runs on push to main and PRs
- Steps: install → lint → test → build
Husky Hooks:
- Pre-commit: (Biome check)
lint-staged - Pre-push:
bun run typecheck
Biome:
- in each project
biome.json - 100 character line width
- Double quotes, semicolons
Vitest配置:
- 每个项目下的
vitest.config.ts - 代码行、函数、分支覆盖率阈值为80%
- 使用覆盖率统计器
@vitest/coverage-v8
GitHub Actions:
.github/workflows/ci.yml- 推送至main分支及PR时自动运行
- 步骤:安装依赖 → 代码检查 → 运行测试 → 构建项目
Husky钩子:
- 提交前:(Biome代码检查)
lint-staged - 推送前:(类型检查)
bun run typecheck
Biome配置:
- 每个项目下的
biome.json - 行宽限制为100字符
- 使用双引号和分号
Phase 5: Verification
阶段5:验证
Run quality gate and report results:
✅ Generation complete!
Quality Report:
- bun install: ✓ succeeded
- bun run lint: ✓ 0 errors
- bun run test: ✓ 24 tests passed
- Coverage: 82% (threshold: 80%)
Ready to run:
cd [project]
bun dev运行质量门禁并报告结果:
✅ 生成完成!
质量报告:
- bun install: ✓ 成功
- bun run lint: ✓ 0个错误
- bun run test: ✓ 24个测试通过
- 覆盖率:82%(阈值:80%)
启动命令:
cd [project]
bun devUsage
使用方法
bash
undefinedbash
undefinedCreate workspace with PRD-style prompt
通过PRD风格的描述创建工作区
python3 ~/.claude/skills/fullstack-workspace-init/scripts/init-workspace.py
--root ~/www/myproject
--name "My Project"
--brief "A task management app where users can create tasks with titles and due dates, organize them into projects, and mark them complete."
--root ~/www/myproject
--name "My Project"
--brief "A task management app where users can create tasks with titles and due dates, organize them into projects, and mark them complete."
python3 ~/.claude/skills/fullstack-workspace-init/scripts/init-workspace.py
--root ~/www/myproject
--name "My Project"
--brief "一个任务管理应用,用户可以创建包含标题和截止日期的任务,将其组织到项目中,并标记为完成状态。"
--root ~/www/myproject
--name "My Project"
--brief "一个任务管理应用,用户可以创建包含标题和截止日期的任务,将其组织到项目中,并标记为完成状态。"
Or interactive mode (prompts for brief)
或使用交互模式(提示输入描述)
python3 ~/.claude/skills/fullstack-workspace-init/scripts/init-workspace.py
--root ~/www/myproject
--name "My Project"
--interactive
--root ~/www/myproject
--name "My Project"
--interactive
---python3 ~/.claude/skills/fullstack-workspace-init/scripts/init-workspace.py
--root ~/www/myproject
--name "My Project"
--interactive
--root ~/www/myproject
--name "My Project"
--interactive
---Generated Structure
生成的项目结构
myproject/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI/CD
├── .husky/
│ ├── pre-commit # Lint staged files
│ └── pre-push # Type check
├── .agents/ # AI documentation
├── package.json # Workspace root
├── biome.json # Root linting config
│
├── api/ # NestJS backend
│ ├── apps/api/src/
│ │ ├── main.ts
│ │ ├── app.module.ts
│ │ ├── auth/
│ │ │ ├── guards/clerk-auth.guard.ts
│ │ │ ├── guards/clerk-auth.guard.spec.ts # Auth guard tests
│ │ │ └── decorators/current-user.decorator.ts
│ │ └── collections/
│ │ └── {entity}/
│ │ ├── {entity}.controller.ts
│ │ ├── {entity}.controller.spec.ts # Controller tests
│ │ ├── {entity}.service.ts
│ │ └── {entity}.service.spec.ts # Service tests
│ ├── apps/api/test/
│ │ ├── {entity}.e2e-spec.ts # E2E tests
│ │ └── setup.ts # E2E test setup
│ ├── vitest.config.ts
│ ├── package.json
│ └── .env.example
│
├── frontend/ # NextJS apps
│ ├── apps/dashboard/
│ │ ├── app/
│ │ │ ├── layout.tsx
│ │ │ ├── page.tsx
│ │ │ ├── sign-in/[[...sign-in]]/page.tsx
│ │ │ ├── sign-up/[[...sign-up]]/page.tsx
│ │ │ └── {entity}/ # Generated per entity
│ │ ├── src/test/
│ │ │ └── setup.ts # Test setup with Clerk mocks
│ │ ├── middleware.ts # Clerk route protection
│ │ └── providers/
│ │ └── clerk-provider.tsx
│ ├── packages/
│ │ ├── components/
│ │ │ ├── {entity}-list.tsx
│ │ │ ├── {entity}-list.spec.tsx # Component tests
│ │ │ ├── {entity}-form.tsx
│ │ │ └── {entity}-form.spec.tsx # Component tests
│ │ ├── hooks/
│ │ │ ├── use-{entities}.ts
│ │ │ └── use-{entities}.spec.ts # Hook tests
│ │ ├── services/ # API clients
│ │ └── interfaces/
│ ├── vitest.config.ts # Frontend test config (jsdom)
│ └── package.json
│
├── mobile/ # React Native + Expo (optional)
│ └── ...
│
└── packages/ # Shared packages
└── packages/
├── common/
│ ├── interfaces/
│ └── enums/
└── helpers/myproject/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI/CD流水线
├── .husky/
│ ├── pre-commit # 检查暂存文件
│ └── pre-push # 类型检查
├── .agents/ # AI相关文档
├── package.json # 工作区根配置
├── biome.json # 根目录代码检查配置
│
├── api/ # NestJS后端
│ ├── apps/api/src/
│ │ ├── main.ts
│ │ ├── app.module.ts
│ │ ├── auth/
│ │ │ ├── guards/clerk-auth.guard.ts
│ │ │ ├── guards/clerk-auth.guard.spec.ts # 认证守卫测试
│ │ │ └── decorators/current-user.decorator.ts
│ │ └── collections/
│ │ └── {entity}/
│ │ ├── {entity}.controller.ts
│ │ ├── {entity}.controller.spec.ts # 控制器测试
│ │ ├── {entity}.service.ts
│ │ └── {entity}.service.spec.ts # 服务层测试
│ ├── apps/api/test/
│ │ ├── {entity}.e2e-spec.ts # E2E测试
│ │ └── setup.ts # E2E测试配置
│ ├── vitest.config.ts
│ ├── package.json
│ └── .env.example
│
├── frontend/ # NextJS应用
│ ├── apps/dashboard/
│ │ ├── app/
│ │ │ ├── layout.tsx
│ │ │ ├── page.tsx
│ │ │ ├── sign-in/[[...sign-in]]/page.tsx
│ │ │ ├── sign-up/[[...sign-up]]/page.tsx
│ │ │ └── {entity}/ # 按实体生成
│ │ ├── src/test/
│ │ │ └── setup.ts # 带有Clerk模拟的测试配置
│ │ ├── middleware.ts # Clerk路由保护
│ │ └── providers/
│ │ └── clerk-provider.tsx
│ ├── packages/
│ │ ├── components/
│ │ │ ├── {entity}-list.tsx
│ │ │ ├── {entity}-list.spec.tsx # 组件测试
│ │ │ ├── {entity}-form.tsx
│ │ │ └── {entity}-form.spec.tsx # 组件测试
│ │ ├── hooks/
│ │ │ ├── use-{entities}.ts
│ │ │ └── use-{entities}.spec.ts # Hook测试
│ │ ├── services/ # API客户端
│ │ └── interfaces/
│ ├── vitest.config.ts # 前端测试配置(jsdom)
│ └── package.json
│
├── mobile/ # React Native + Expo(可选)
│ └── ...
│
└── packages/ # 共享包
└── packages/
├── common/
│ ├── interfaces/
│ └── enums/
└── helpers/Key Patterns
核心代码模式
Backend Controller Pattern
后端控制器模式
typescript
@ApiTags('tasks')
@ApiBearerAuth()
@UseGuards(ClerkAuthGuard)
@Controller('tasks')
export class TasksController {
constructor(private readonly tasksService: TasksService) {}
@Post()
@ApiOperation({ summary: 'Create a new task' })
create(
@Body() createTaskDto: CreateTaskDto,
@CurrentUser() user: { userId: string },
) {
return this.tasksService.create(createTaskDto, user.userId);
}
// ... full CRUD
}typescript
@ApiTags('tasks')
@ApiBearerAuth()
@UseGuards(ClerkAuthGuard)
@Controller('tasks')
export class TasksController {
constructor(private readonly tasksService: TasksService) {}
@Post()
@ApiOperation({ summary: '创建新任务' })
create(
@Body() createTaskDto: CreateTaskDto,
@CurrentUser() user: { userId: string },
) {
return this.tasksService.create(createTaskDto, user.userId);
}
// ... 完整CRUD实现
}Backend Service Pattern
后端服务层模式
typescript
@Injectable()
export class TasksService {
constructor(
@InjectModel(Task.name) private taskModel: Model<TaskDocument>,
) {}
async create(createTaskDto: CreateTaskDto, userId: string): Promise<Task> {
const task = new this.taskModel({ ...createTaskDto, userId });
return task.save();
}
// ... full CRUD with userId filtering
}typescript
@Injectable()
export class TasksService {
constructor(
@InjectModel(Task.name) private taskModel: Model<TaskDocument>,
) {}
async create(createTaskDto: CreateTaskDto, userId: string): Promise<Task> {
const task = new this.taskModel({ ...createTaskDto, userId });
return task.save();
}
// ... 带userId过滤的完整CRUD实现
}Frontend Component Pattern
前端组件模式
typescript
'use client';
import { useEffect, useState } from 'react';
import { TaskService } from '@services/task.service';
import { Task } from '@interfaces/task.interface';
export function TaskList() {
const [tasks, setTasks] = useState<Task[]>([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
const controller = new AbortController();
TaskService.getAll({ signal: controller.signal })
.then(setTasks)
.finally(() => setLoading(false));
return () => controller.abort();
}, []);
// ... render
}typescript
'use client';
import { useEffect, useState } from 'react';
import { TaskService } from '@services/task.service';
import { Task } from '@interfaces/task.interface';
export function TaskList() {
const [tasks, setTasks] = useState<Task[]>([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
const controller = new AbortController();
TaskService.getAll({ signal: controller.signal })
.then(setTasks)
.finally(() => setLoading(false));
return () => controller.abort();
}, []);
// ... 渲染逻辑
}Additional Scripts
附加脚本
bash
undefinedbash
undefinedAdd a new entity to existing project
为现有项目添加新实体
python3 ~/.claude/skills/fullstack-workspace-init/scripts/add-entity.py
--root ~/www/myproject
--name "comment"
--fields "content:string,taskId:string"
--root ~/www/myproject
--name "comment"
--fields "content:string,taskId:string"
python3 ~/.claude/skills/fullstack-workspace-init/scripts/add-entity.py
--root ~/www/myproject
--name "comment"
--fields "content:string,taskId:string"
--root ~/www/myproject
--name "comment"
--fields "content:string,taskId:string"
Add a new frontend app
添加新的前端应用
python3 ~/.claude/skills/fullstack-workspace-init/scripts/add-frontend-app.py
--root ~/www/myproject/frontend
--name admin
--root ~/www/myproject/frontend
--name admin
---python3 ~/.claude/skills/fullstack-workspace-init/scripts/add-frontend-app.py
--root ~/www/myproject/frontend
--name admin
--root ~/www/myproject/frontend
--name admin
---Development Commands
开发命令
After scaffolding:
bash
cd myproject脚手架生成完成后:
bash
cd myprojectInstall all dependencies
安装所有依赖
bun install
bun install
Start all services (backend + frontend)
启动所有服务(后端 + 前端)
bun dev
bun dev
Or start individually
或单独启动
bun run dev:api # Backend on :3001
bun run dev:frontend # Frontend on :3000
bun run dev:mobile # Mobile via Expo
bun run dev:api # 后端运行在 :3001
bun run dev:frontend # 前端运行在 :3000
bun run dev:mobile # 通过Expo启动移动端
Quality commands
质量保障命令
bun run lint # Check code style
bun run test # Run tests
bun run test:coverage # Run with coverage
bun run typecheck # Type checking
---bun run lint # 检查代码风格
bun run test # 运行测试
bun run test:coverage # 运行测试并生成覆盖率报告
bun run typecheck # 类型检查
---Environment Variables
环境变量
Create files based on :
.env.env.exampleAPI (.env):
PORT=3001
MONGODB_URI=mongodb://localhost:27017/myproject
CLERK_SECRET_KEY=sk_test_...Frontend (.env.local):
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_API_URL=http://localhost:3001基于创建文件:
.env.example.envAPI(.env):
PORT=3001
MONGODB_URI=mongodb://localhost:27017/myproject
CLERK_SECRET_KEY=sk_test_...前端(.env.local):
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_API_URL=http://localhost:3001References
参考资源
- - Code generation templates
references/templates/- - NestJS service unit test template
service.spec.template.ts - - NestJS controller unit test template
controller.spec.template.ts - - E2E test template with supertest + MongoDB Memory Server
e2e.spec.template.ts - - React component test template
component.spec.template.tsx - - React hook test template
hook.spec.template.ts - - Frontend test setup with Clerk mocks
test-setup.template.ts
- - Backend Vitest configuration (80% coverage)
references/vitest.config.ts - - Frontend Vitest configuration (jsdom)
references/vitest.config.frontend.ts - - CI/CD workflow
references/github-actions/ci.yml - - Architectural decisions
references/architecture-guide.md - - Coding rules
references/coding-standards.md
- - 代码生成模板
references/templates/- - NestJS服务层单元测试模板
service.spec.template.ts - - NestJS控制器单元测试模板
controller.spec.template.ts - - 基于supertest + MongoDB Memory Server的E2E测试模板
e2e.spec.template.ts - - React组件测试模板
component.spec.template.tsx - - React Hook测试模板
hook.spec.template.ts - - 带有Clerk模拟的前端测试配置模板
test-setup.template.ts
- - 后端Vitest配置(80%覆盖率阈值)
references/vitest.config.ts - - 前端Vitest配置(jsdom)
references/vitest.config.frontend.ts - - CI/CD工作流模板
references/github-actions/ci.yml - - 架构决策文档
references/architecture-guide.md - - 编码规范文档
references/coding-standards.md