القائمة
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