react-typescript-architecture

name

react-typescript-architecture

description

Use this skill for React + TypeScript implementation, refactoring, and review tasks involving components, hooks, props typing, children typing, refs, effects, context, reducers, events, forms, utility functions, async UI state, generic components, type modeling, module/export conventions, and React architecture decisions. Trigger this skill when creating or refactoring React TypeScript code and when choosing the right abstraction boundary for maintainable React applications.

Purpose

This skill gives Codex a practical React + TypeScript architecture playbook aligned with current React guidance.

Use it when the task involves:

• creating or refactoring React UI in TypeScript
• choosing between components, hooks, utilities, context, reducers, or typed helpers
• improving maintainability, typing quality, and feature boundaries
• applying current React recommendations around refs and manual memoization

This skill is guidance-oriented. It does not replace project-specific UI/system skills such as shadcn-ui.

Current guidance baked into this skill

Use the following default assumptions unless the repository explicitly requires older patterns:

1. Prefer function components.
2. Avoid React.FC by default.
3. This project uses React 18.3.1 — forwardRef is still required when forwarding refs. Do not use the React 19 ref-as-prop pattern here.
4. Do not add useMemo, useCallback, or memo automatically. Use them only when there is a real stability or performance reason.
5. If React Compiler is enabled, be even more conservative with manual memoization.
6. Prefer named exports for feature modules unless the repository clearly standardizes on default exports.

When to use this skill

Use this skill when the task includes any of the following:

• component design and decomposition
• props typing
• children typing
• refs and imperative APIs
• hook design and extraction
• context/provider architecture
• reducer design
• event and form typing
• utility and normalization helpers used by React features
• async UI state modeling
• generic component design
• unions, narrowing, and helper type design
• React module/export conventions
• React code review and anti-pattern cleanup

Do not use this skill when:

• the task is backend-only
• the task is non-React frontend work with no significant React/TS design decisions
• the task is styling-only and no React architecture decision is needed

Core principles

1. Choose the smallest correct abstraction.

• Keep logic in the component only when it is primarily rendering + interaction.
• Extract hooks for reusable stateful UI logic.
• Keep non-React logic in utilities.

2. Type public contracts explicitly.

• Props, hook returns, context values, reducer actions, command callbacks, and reusable utility signatures must be explicit and readable.

3. Keep state boundaries clean.

• Prefer local state first.
• Lift state only when coordination is needed.
• Use context sparingly.
• Use reducers only when transitions justify them.

4. Prefer clear unions over flag soup.

• Use discriminated unions for async or multi-mode UI state.

5. Avoid unsafe assertions.

• Prefer narrowing, guards, or better contract design over broad as casting.

6. Prefer modern React 18 defaults.

• Use forwardRef when a component needs to expose a ref to its parent (React 18 pattern).
• No automatic manual memoization.
• No React.FC.

Entity map

Components

Use for rendering + interaction.

Hooks

Use for reusable or dense stateful UI logic.

Context

Use for bounded subtree shared state/behavior.

Reducers

Use for coordinated state transitions.

Utilities

Use for pure transforms, normalization, formatting, and type guards.

Type modules

Use for domain contracts, discriminated unions, helper types, and reusable narrowing logic.

Default conventions

• Prefer export const Component = (...) => {} for components and hooks.
• Prefer named exports by default.
• Prefer object return shapes for non-trivial hooks.
• Prefer children?: ReactNode for ordinary children-bearing components.
• Prefer typed accessor hooks for nullable contexts.
• Prefer ComponentPropsWithoutRef / ComponentProps utilities where they meaningfully simplify wrapper typing.
• Prefer satisfies when checking object shape while preserving literal precision.

Project-specific context for numpad

File structure

What	Where
Feature components	src/features/<feature>/components/<ComponentName>.tsx
Feature sub-components	src/features/<feature>/components/<feature-area>/<ComponentName>.tsx
Shared shadcn primitives	src/shared/ui/components/<name>.tsx
Shared utilities	src/shared/lib/utils.ts (cn, etc.)
Shared types	src/shared/types/<domain>.ts
Entity types	src/entities/<domain>/<domain>.types.ts

Import alias: @/ → src/. Example: import { Button } from "@/shared/ui/components/button".

State ownership rules for this project

• Workspace state (documents, rawText, lines, tables) → useWorkspaceStore from @/app/store/workspace.store. Do not create a parallel Context or reducer for this.
• Settings state (theme, AI, locale) → useSettingsStore from @/features/settings/settings.store. Do not duplicate.
• Transient UI state (open/close, draft values, local selection) → useState local to the component.
• Always use granular selectors on Zustand stores — never destructure the whole store object.
• For Zustand selector and action patterns, see .codex/skills/shadcn-ui/component-hooks-model.md.

Naming conventions

• Screen-level components: <Name>Screen.tsx (e.g. WorkspaceScreen, QuickCalcScreen)
• Pane-level components: <Name>Pane.tsx (e.g. WorkspaceEditorPane, WorkspaceInspectorPane)
• Feature panels: <Feature>Panel.tsx or <Feature>Sheet.tsx
• Hook files: use-<name>.ts
• Native (Tauri) wrappers: <domain>.native.ts

Skill resources

Use these companion files when relevant:

• component-patterns.md
• hooks-patterns.md
• context-reducer-patterns.md
• forms-events-patterns.md
• refs-patterns.md
• effects-patterns.md
• utilities-patterns.md
• async-state-patterns.md
• generic-components-patterns.md
• types-and-unions-patterns.md
• exports-and-module-patterns.md
• anti-patterns.md

Output expectations for Codex

When this skill is selected, Codex should:

1. identify the relevant React TypeScript entity boundaries
2. choose the smallest correct abstraction
3. follow current React guidance around refs and memoization
4. keep public contracts explicit
5. avoid React.FC, unnecessary forwardRef, and unnecessary memoization
6. produce readable, maintainable, repo-consistent code