- name
- frontend-technical-spec
- description
- Defines React environment, component architecture, state/data flow, build verification, and frontend non-functional criteria from repository evidence. Use when configuring or designing a React frontend, its build, or its runtime boundaries.
Technical Design Rules (Frontend)
Prerequisite Detection
Inspect package.json, the lockfile, TypeScript/build configuration, CI definitions, and representative components before applying a tool- or framework-specific rule. Treat React, Vite, Next.js, a state library, form library, or script as available only when repository evidence names it. Label surrounding-pattern conclusions as inferred. When a missing decision changes rendering architecture, compatibility, security, or verification, stop and name the exact evidence or user decision required.
Basic Technology Stack Policy
These rules apply when repository configuration confirms a TypeScript-based React application. Select architecture by mapping current requirements and constraints to component responsibilities, state ownership, server/client boundaries, and observable verification points.
Environment Variable Management and Security
Environment Variable Management
- Use the build tool's client-exposure mechanism: Browser code can read only values explicitly exposed by the configured bundler/framework; server-only environment access remains outside client bundles
- Centrally manage environment variables through configuration layer
- Parse exposed values at one typed configuration boundary before application use
- Give a value a default only when requirements define valid behavior for absence; otherwise fail startup/build validation with the variable name and expected format
// Build tool environment variables (public values only; client-exposed vars need the VITE_ prefix)
const config = {
apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
appName: import.meta.env.VITE_APP_NAME || 'My App'
}
// Does not work in frontend
const apiUrl = process.env.API_URL
Security (Client-side Constraints)
- CRITICAL: All frontend code is public and visible in browser
- Keep secrets server-side: Client-exposed configuration contains public values only; a backend or trusted service owns API keys, tokens, and credentials
- Keep local
.envfiles outside version control and provide non-secret example files for required variable names