fullstack-workspace-init

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Full 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:
  • auth/guards/clerk-auth.guard.ts
    - Token verification guard
  • auth/decorators/current-user.decorator.ts
    - User extraction decorator
Frontend:
  • providers/clerk-provider.tsx
    - ClerkProvider wrapper
  • app/sign-in/[[...sign-in]]/page.tsx
    - Sign in page
  • app/sign-up/[[...sign-up]]/page.tsx
    - Sign up page
  • middleware.ts
    - Protected route middleware
Environment:
  • .env.example
    with all required variables
生成Clerk身份验证相关代码:
后端:
  • auth/guards/clerk-auth.guard.ts
    - Token验证守卫
  • auth/decorators/current-user.decorator.ts
    - 用户信息提取装饰器
前端:
  • providers/clerk-provider.tsx
    - ClerkProvider包装组件
  • 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 Server
Frontend (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:
  • vitest.config.ts
    in each project
  • 80% coverage threshold for lines, functions, branches
  • @vitest/coverage-v8
    provider
GitHub Actions:
  • .github/workflows/ci.yml
  • Runs on push to main and PRs
  • Steps: install → lint → test → build
Husky Hooks:
  • Pre-commit:
    lint-staged
    (Biome check)
  • Pre-push:
    bun run typecheck
Biome:
  • biome.json
    in each project
  • 100 character line width
  • Double quotes, semicolons
Vitest配置:
  • 每个项目下的
    vitest.config.ts
  • 代码行、函数、分支覆盖率阈值为80%
  • 使用
    @vitest/coverage-v8
    覆盖率统计器
GitHub Actions:
  • .github/workflows/ci.yml
  • 推送至main分支及PR时自动运行
  • 步骤:安装依赖 → 代码检查 → 运行测试 → 构建项目
Husky钩子:
  • 提交前:
    lint-staged
    (Biome代码检查)
  • 推送前:
    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 dev

Usage

使用方法

bash
undefined
bash
undefined

Create 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."
python3 ~/.claude/skills/fullstack-workspace-init/scripts/init-workspace.py
--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

---
python3 ~/.claude/skills/fullstack-workspace-init/scripts/init-workspace.py
--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
undefined
bash
undefined

Add 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"
python3 ~/.claude/skills/fullstack-workspace-init/scripts/add-entity.py
--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

---
python3 ~/.claude/skills/fullstack-workspace-init/scripts/add-frontend-app.py
--root ~/www/myproject/frontend
--name admin

---

Development Commands

开发命令

After scaffolding:
bash
cd myproject
脚手架生成完成后:
bash
cd myproject

Install 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
.env
files based on
.env.example
:
API (.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
创建
.env
文件:
API(.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:3001

References

参考资源

  • references/templates/
    - Code generation templates
    • service.spec.template.ts
      - NestJS service unit test template
    • controller.spec.template.ts
      - NestJS controller unit test template
    • e2e.spec.template.ts
      - E2E test template with supertest + MongoDB Memory Server
    • component.spec.template.tsx
      - React component test template
    • hook.spec.template.ts
      - React hook test template
    • test-setup.template.ts
      - Frontend test setup with Clerk mocks
  • references/vitest.config.ts
    - Backend Vitest configuration (80% coverage)
  • references/vitest.config.frontend.ts
    - Frontend Vitest configuration (jsdom)
  • references/github-actions/ci.yml
    - CI/CD workflow
  • references/architecture-guide.md
    - Architectural decisions
  • references/coding-standards.md
    - Coding rules
  • references/templates/
    - 代码生成模板
    • service.spec.template.ts
      - NestJS服务层单元测试模板
    • controller.spec.template.ts
      - NestJS控制器单元测试模板
    • e2e.spec.template.ts
      - 基于supertest + MongoDB Memory Server的E2E测试模板
    • component.spec.template.tsx
      - React组件测试模板
    • hook.spec.template.ts
      - React Hook测试模板
    • test-setup.template.ts
      - 带有Clerk模拟的前端测试配置模板
  • references/vitest.config.ts
    - 后端Vitest配置(80%覆盖率阈值)
  • references/vitest.config.frontend.ts
    - 前端Vitest配置(jsdom)
  • references/github-actions/ci.yml
    - CI/CD工作流模板
  • references/architecture-guide.md
    - 架构决策文档
  • references/coding-standards.md
    - 编码规范文档