From 2fb29d236cecbe79e100b58408fd36ae650d1c14 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 29 Mar 2026 17:14:47 +0000 Subject: [PATCH] docs(frontend): autonomous architectural standardization for frontend documentation - Refactored YAML frontmatter across `frontend` docs to enforce AI-ready SEO structure and precise fields requested. - Standardized markdown heading constraints across technologies ensuring accurate rule definitions using a 4-step bad-to-solution approach. Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- frontend/qwik/readme.md | 10 ++-- frontend/react/performance.md | 6 +- frontend/react/readme.md | 6 +- frontend/solidjs/readme.md | 10 ++-- frontend/typescript/readme.md | 100 +++++++++++++++++----------------- 5 files changed, 62 insertions(+), 70 deletions(-) diff --git a/frontend/qwik/readme.md b/frontend/qwik/readme.md index 883ca99..dfb18ac 100644 --- a/frontend/qwik/readme.md +++ b/frontend/qwik/readme.md @@ -29,19 +29,19 @@ last_updated: 2026-03-22 ## 🚀 I. Basics & Popular -## 1. Passing Closures as Props +### 1. Passing Closures as Props **Context:** Component Props -### ❌ Bad Practice +#### ❌ Bad Practice ```tsx const Component = ({ onClick }) => ; ``` -### ⚠️ Problem +#### ⚠️ Problem Closures cannot be serialized natively by Qwik, breaking resumability and throwing an error. -### ✅ Best Practice +#### ✅ Best Practice ```tsx const Component = component$(({ onClick$ }: { onClick$: PropFunction<() => void> }) => ( )); ``` -### 🚀 Solution +#### 🚀 Solution Use the `$` suffix (`onClick$`) to mark the prop as a `PropFunction`, allowing Qwik to serialize the closure and load it lazily. diff --git a/frontend/react/performance.md b/frontend/react/performance.md index 4d8e44d..485413a 100644 --- a/frontend/react/performance.md +++ b/frontend/react/performance.md @@ -1,14 +1,10 @@ --- description: Vibe coding guidelines and architectural constraints for React Performance within the frontend domain. -tags: [react, performance, use, react-compiler, best-practices, architecture, clean-code] -topic: React Performance -complexity: Architect -last_evolution: 2026-03-22 -vibe_coding_ready: true technology: React domain: frontend level: Senior/Architect version: "19+" +tags: [react, performance, use, react-compiler, best-practices, architecture, clean-code] ai_role: Senior React Performance Expert last_updated: 2026-03-22 --- diff --git a/frontend/react/readme.md b/frontend/react/readme.md index 6082563..32ef24a 100644 --- a/frontend/react/readme.md +++ b/frontend/react/readme.md @@ -1,14 +1,10 @@ --- description: Vibe coding guidelines and architectural constraints for React within the frontend domain. -tags: [react, best-practices, architecture, clean-code, scalable-code, modern-react, server-components] -topic: React -complexity: Architect -last_evolution: 2026-03-22 -vibe_coding_ready: true technology: React domain: frontend level: Senior/Architect version: "19+" +tags: [react, best-practices, architecture, clean-code, scalable-code, modern-react, server-components] ai_role: Senior React Expert last_updated: 2026-03-22 --- diff --git a/frontend/solidjs/readme.md b/frontend/solidjs/readme.md index fa1a2cd..38af2aa 100644 --- a/frontend/solidjs/readme.md +++ b/frontend/solidjs/readme.md @@ -29,17 +29,17 @@ last_updated: 2026-03-22 ## 🚀 I. Basics & Popular -## 1. Using JSX Map for Lists +### 1. Using JSX Map for Lists **Context:** Rendering Lists -### ❌ Bad Practice +#### ❌ Bad Practice ```tsx return ; ``` -### ⚠️ Problem +#### ⚠️ Problem Using `.map` creates the DOM nodes once and does not react to array changes optimally, leading to unnecessary re-renders or lost reactivity. -### ✅ Best Practice +#### ✅ Best Practice ```tsx return ; ``` -### 🚀 Solution +#### 🚀 Solution Use the `` component. It caches DOM elements and handles granular updates when the array changes. diff --git a/frontend/typescript/readme.md b/frontend/typescript/readme.md index 25c0946..19700b2 100644 --- a/frontend/typescript/readme.md +++ b/frontend/typescript/readme.md @@ -15,17 +15,17 @@ last_updated: 2026-03-22 ## 🚀 I. Fundamentals (1-10) -## ⚡ 1. `any` vs `unknown` +### ⚡ 1. `any` vs `unknown` **Context:** Handling data of an uncertain type. `any` disables all type-checking, while `unknown` forces safety. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript function process(data: any) { console.log(data.name); // No error, but might crash at runtime } ``` -### ⚠️ Problem +#### ⚠️ Problem `any` is a "get out of jail free" card that propagates through the codebase, effectively turning off TypeScript's benefits and hiding potential runtime exceptions. -### ✅ Best Practice +#### ✅ Best Practice ```typescript function process(data: unknown) { if (data && typeof data === 'object' && 'name' in data) { @@ -33,74 +33,74 @@ function process(data: unknown) { } } ``` -### 🚀 Solution +#### 🚀 Solution Use `unknown` for values whose type is not yet determined. It requires a type check or assertion before usage, ensuring the developer acknowledges the data's structure. --- -## ⚡ 2. `null` vs `undefined` in APIs +### ⚡ 2. `null` vs `undefined` in APIs **Context:** Distinguishing between "value not provided" and "value is empty." -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript interface UserResponse { bio: string | null | undefined; } ``` -### ⚠️ Problem +#### ⚠️ Problem Using both creates ambiguity. In JSON, `undefined` properties are often stripped, while `null` is preserved. Mixing them increases complexity in conditional checks. -### ✅ Best Practice +#### ✅ Best Practice ```typescript interface UserResponse { bio?: string | null; // Optional if missing, null if explicitly empty } ``` -### 🚀 Solution +#### 🚀 Solution Standardize: use `undefined` (optional properties) for missing keys and `null` for intentional absence of value. Avoid using both for the same field unless strictly required by a legacy API. --- -## ⚡ 3. `Array` vs `T[]` +### ⚡ 3. `Array` vs `T[]` **Context:** Visual consistency in array declarations. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript const users: Array = []; const complex: Array = []; ``` -### ⚠️ Problem +#### ⚠️ Problem `Array` is more verbose and can be confused with other generic types. It is harder to scan in complex signatures. -### ✅ Best Practice +#### ✅ Best Practice ```typescript const users: User[] = []; const complex: (string | number)[] = []; ``` -### 🚀 Solution +#### 🚀 Solution Prefer the shorthand `T[]`. It is idiomatic, more readable, and clearly distinguishes arrays from other generic containers like `Record` or `Promise`. --- -## ⚡ 4. `interface` vs `type` +### ⚡ 4. `interface` vs `type` **Context:** Defining object structures and aliases. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript interface Point { x: number; y: number; } interface ID extends string {} // Error: Interface can only extend objects ``` -### ⚠️ Problem +#### ⚠️ Problem `interface` is limited to objects and allows "declaration merging," which can lead to accidental property overrides in global scopes. -### ✅ Best Practice +#### ✅ Best Practice ```typescript type Point = { x: number; y: number; }; type ID = string; type Union = 'A' | 'B'; ``` -### 🚀 Solution +#### 🚀 Solution Use `type` for almost everything (unions, primitives, intersections). Use `interface` only when you specifically need declaration merging or for public library APIs where consumers might need to extend types. --- -## ⚡ 5. Function Overloads vs Union Types +### ⚡ 5. Function Overloads vs Union Types **Context:** Handling functions with different input/output combinations. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript function format(input: string): string; function format(input: number): string; @@ -108,51 +108,51 @@ function format(input: any): string { return String(input); } ``` -### ⚠️ Problem +#### ⚠️ Problem Overloads are verbose and can be harder to implement correctly. They often require `any` or complex type-casting in the implementation body. -### ✅ Best Practice +#### ✅ Best Practice ```typescript function format(input: string | number): string { return String(input); } ``` -### 🚀 Solution +#### 🚀 Solution Prefer Union types when the implementation logic is identical for all types. Reserve overloads only for cases where the return type strictly depends on the input type and cannot be expressed via generics. --- -## 🎯 6. Global Scope Pollution (Legacy Namespaces) +### 🎯 6. Global Scope Pollution (Legacy Namespaces) **Context:** Organizing code in the ES Module era. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript namespace Utils { export const log = (msg: string) => console.log(msg); } ``` -### ⚠️ Problem +#### ⚠️ Problem Namespaces are a legacy TypeScript feature. They don't play well with modern bundlers (Tree Shaking), are harder to test, and can lead to naming collisions in the global scope. -### ✅ Best Practice +#### ✅ Best Practice ```typescript // utils.ts export const log = (msg: string) => console.log(msg); ``` -### 🚀 Solution +#### 🚀 Solution Use ES Modules (`export`/`import`). They are the industry standard, supported by all modern environments, and allow for better static analysis. --- -## ⚡ 7. `enum` vs `const object` +### ⚡ 7. `enum` vs `const object` **Context:** Grouping related constants. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript enum Status { Active, Inactive } ``` -### ⚠️ Problem +#### ⚠️ Problem Enums generate extra runtime code and have "reverse mapping" behavior that can lead to bugs (e.g., `Status[0]` returns "Active"). They also don't align with "TypeScript as a type-only layer." -### ✅ Best Practice +#### ✅ Best Practice ```typescript const STATUS = { ACTIVE: 'active', @@ -161,43 +161,43 @@ const STATUS = { type Status = typeof STATUS[keyof typeof STATUS]; ``` -### 🚀 Solution +#### 🚀 Solution Use `const` objects with `as const` and a derived union type. This is more predictable, emits cleaner code, and is easier to iterate over. --- -## ⚡ 8. Explicit `any` in Parameters +### ⚡ 8. Explicit `any` in Parameters **Context:** Enforcing strict type safety. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript function save(data) { // Implicit any if strict: false db.push(data); } ``` -### ⚠️ Problem +#### ⚠️ Problem Implicit `any` bypasses the compiler's ability to verify data flow, leading to "undefined is not a function" errors that TypeScript was designed to prevent. -### ✅ Best Practice +#### ✅ Best Practice ```typescript function save(data: UserData) { db.push(data); } ``` -### 🚀 Solution +#### 🚀 Solution Enable `noImplicitAny: true` in `tsconfig.json`. Always define specific types or use `unknown` if the type is truly dynamic. --- -## ⚡ 9. Manual Type Guards vs Type Predicates +### ⚡ 9. Manual Type Guards vs Type Predicates **Context:** Narrowing types inside conditional blocks. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript if (typeof input === 'object' && input !== null && 'admin' in input) { const isAdmin = (input as any).admin; } ``` -### ⚠️ Problem +#### ⚠️ Problem Repeating complex checks is error-prone and requires manual casting (`as any`) which breaks safety. -### ✅ Best Practice +#### ✅ Best Practice ```typescript function isAdmin(user: unknown): user is Admin { return !!user && typeof user === 'object' && 'admin' in user; @@ -207,24 +207,24 @@ if (isAdmin(input)) { console.log(input.admin); // input is automatically narrowed to Admin } ``` -### 🚀 Solution +#### 🚀 Solution Use Type Predicates (`arg is Type`) to create reusable, safe narrowing functions. --- -## ⚡ 10. Triple-Slash Directives +### ⚡ 10. Triple-Slash Directives **Context:** Referencing types or files. -### ❌ Bad Practice +#### ❌ Bad Practice ```typescript /// ``` -### ⚠️ Problem +#### ⚠️ Problem Triple-slash directives are legacy syntax. They make dependencies implicit and can lead to compilation order issues. -### ✅ Best Practice +#### ✅ Best Practice ```typescript import { MyType } from './types'; ``` -### 🚀 Solution +#### 🚀 Solution Use standard ES `import` statements. Manage global types via `tsconfig.json` `types` array if necessary. ---