菜单
Frontend technical design rules including environment variables, architecture design, data flow, Nx workspace conventions, and build/testing commands.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Universal coding standards for implementation, code quality, testing, and refactoring. Covers anti-patterns, type safety, debugging, Red-Green-Refactor development, test design, code duplication (Rule of Three), decision frameworks, and impact analysis. Use when implementing features, reviewing code quality, fixing bugs, or refactoring.
Enforce unidirectional flow: state → UI (selectors) → actions → updates. Prevent direct store access from components, use granular selectors, implement reselect for complex filtering/sorting/aggregation. Use when designing component data flow or optimizing re-renders.
Implement error handling: try-catch at boundaries, typed errors with instanceof checks, error state in store, error boundaries for components, exponential backoff retry with jitter, Sentry monitoring in production, user-friendly error messages. Use when implementing API calls, form submissions, or component error boundaries.
Implement state management: Zustand slices pattern, manual immutable updates with spread operators, middleware stack (devtools, subscribeWithSelector), Immer decision matrix (4+ spreads → use Immer), transient updates for 10+ updates/sec. Use when implementing stores or managing complex state.
Enforce type safety: Zod runtime validation at boundaries, type guards for discriminated unions, avoid any/unknown, validate before asserting. Optimize Zod with .pick()/.partial() on hot paths. Use when implementing API integrations, form handling, or state management with strict typing.
React/TypeScript frontend development rules including type safety, component design, state management, and error handling.
| name | frontend/technical-spec |
| description | Frontend technical design rules including environment variables, architecture design, data flow, Nx workspace conventions, and build/testing commands. |
The frontend lives inside the Nx workspace and is orchestrated through nx. The primary customer-facing application is the Next.js project at apps/app, with shared UI primitives located in libs/frontend/*. Use Nx generators and project boundaries to keep the architecture consistent. TypeScript-based React application implementation. Architecture patterns should be selected according to project requirements and scale.
process.env does not work in browser environments// Build tool environment variables (public values only)
const config = {
apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
appName: import.meta.env.APP_NAME || 'My App',
};
// Does not work in frontend
const apiUrl = process.env.API_URL;
.env files in Git (same as backend)Correct Approach for Secrets:
// Security risk: API key exposed in browser
const apiKey = import.meta.env.API_KEY;
const response = await fetch(`https://api.example.com/data?key=${apiKey}`);
// Correct: Backend manages secrets, frontend accesses via proxy
const response = await fetch('/api/data'); // Backend handles API key authentication
apps/app. Reusable view logic or utilities must live under the appropriate libs/frontend/... subdirectory (components, hooks, lib, shared-ui, story-editor).nx g @nx/next:component, nx g @nx/react:library) to inherit workspace standards (naming, testing, linting).scope:frontend, type:ui, etc.). Add dependency tags before importing across feature areas.nx graph when designing features to understand the dependency impact and to avoid unintended cross-package coupling.Strictly adhere to selected project patterns. Project-specific details reference docs/rules/architecture/.
React Component Architecture:
State Management Patterns:
useState for component-specific stateMaintain consistent data flow throughout the React application:
Single Source of Truth: Each piece of state has one authoritative source
Unidirectional Flow: Data flows top-down via props
API Response -> State -> Props -> Render -> UI
User Input -> Event Handler -> State Update -> Re-render
Immutable Updates: Use immutable patterns for state updates
// Immutable state update
setUsers((prev) => [...prev, newUser]);
// Mutable state update (avoid)
users.push(newUser);
setUsers(users);
unknown) -> Type Guard -> State (Type Guaranteed)// Type-safe data flow
async function fetchUser(id: string): Promise<User> {
const response = await fetch(`/api/users/${id}`);
const data: unknown = await response.json();
if (!isUser(data)) {
throw new Error('Invalid user data');
}
return data; // Type guaranteed as User
}
# Development server (Next.js app at apps/app)
nx dev app
# Production build (includes type-checking via Next)
nx build app
# Preview built output locally
nx start app
# Type check shared frontend libraries (adjust list as libs evolve)
nx run-many -t typecheck --projects components,hooks,lib,shared-ui,story-editor
Frontend tests run with Jest through Nx-managed targets.
# Run unit tests for the Next.js app entry point
nx test app
# Run unit tests for all frontend libraries (scope tag)
nx run-many -t test --projects tag:scope:frontend
# Run tests with coverage for all frontend libs
nx run-many -t test --projects tag:scope:frontend -- --coverage
# Start a watch-mode unit test session
nx test components --watch
Quality checks are mandatory upon implementation completion:
Phase 1-3: Basic Checks
nx run-many -t lint --projects app,tag:scope:frontend # Biome (lint + format)
nx run-many -t typecheck --projects tag:scope:frontend # Type-only checks for shared libs
nx build app # TypeScript build & Next.js compilation
Phase 4-5: Tests and Final Confirmation
nx test app # Test execution for entry app
nx run-many -t test --projects tag:scope:frontend --skip-nx-cache -- --coverage --runInBand # Coverage measurement (forces fresh run)
nx run-many -t lint --projects app,tag:scope:frontend --skip-nx-cache # Lint verification without cache
nx run-many -t typecheck --projects tag:scope:frontend --skip-nx-cache # Type-only verification