Skip to main content
skill CX Codex

typescript-rules — Claude Code skill: React/TypeScript rules

A skill that enforces React and TypeScript rules for frontend work: type safety, component structure, state ownership and error handling.

MIT ★ 720 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add shinpr/claude-code-workflows --skill typescript-rules -a claude-code
Open on GitHub

What typescript-rules does

The skill sets rules for TypeScript and React code: which types to use at boundaries with external APIs, localStorage, and URL parameters, when any is acceptable, and how to contain it inside an adapter. It also lists review signals for type complexity, such as prop count, nesting depth, and the number of type assertions in one place.

It covers function components and hooks, the server/client boundary for RSC frameworks through the "use client" directive, state ownership, and error handling split across Error Boundaries, custom hooks, and the API layer. A performance section states that with React Compiler enabled, manual React.memo, useMemo, and useCallback should only be added for a measured bottleneck.

The server/client boundary rules apply only to projects with a server-component runtime; the skill tells you to skip them otherwise.

What it helps with

  • pick between any, unknown, and generics at an external API boundary
  • decide when a component needs splitting based on prop count or nesting
  • split error handling across Error Boundaries, hooks, and the API layer
  • decide whether manual useMemo/useCallback are needed with React Compiler on
  • draw the "use client" boundary in a project with server components

Example prompts for the agent

  • Check the typing of the UserCard component against typescript-rules
  • Split this component using the type-complexity signals from typescript-rules
  • Lay out error handling in the useFetchUser hook per typescript-rules

How to install typescript-rules

1Skills CLI (Vercel)

npx skills add shinpr/claude-code-workflows --skill typescript-rules -a claude-code

2Manually: put the files in place

~/.claude/skills/typescript-rules/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/typescript-rules/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about typescript-rules

How do I install typescript-rules in Claude Code?

Run npx skills add shinpr/claude-code-workflows --skill typescript-rules -a claude-code; the skill lands in ~/.claude/skills/typescript-rules/SKILL.md.

What does the typescript-rules skill do?

It defines rules for React/TypeScript work covering type safety, component structure, state ownership, error handling, and performance. It applies when working on React components, TypeScript code, or frontend features.

Does typescript-rules work in projects without server components?

Yes, the server/client boundary rules built around "use client" only kick in for frameworks with a server-component runtime and are skipped otherwise.

Source text

SKILL.md · MIT
---
name: typescript-rules
description: React/TypeScript frontend development rules including type safety, component design, state management, and error handling. Use when implementing React components, TypeScript code, or frontend features.
---

# TypeScript Development Rules (Frontend)

## Comment Writing Rules

Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough.

- Explain why a component memoizes, guards, or re-renders, not what the JSX renders.
- Record decisions and rationale; leave chronological history to version control.

## Type Safety

**Default Rule**: Prefer `unknown`, generics, or union types over `any`. Retain `any` only when an existing external, generated, or legacy public signature requires it, or when replacing it prevents the project type check from expressing a safe generic relationship. Record the declaration path or type-check result that proves the constraint. When a local adapter can preserve compatibility and expose a safer type within the user request or current task/design artifact, implement the adapter; otherwise confine `any` to the smallest adapter or public-signature boundary, document the reason, and validate untrusted data before it enters typed application code.

**Frontend Boundaries**

- React Props/State: use the declared application types.
- External API responses: treat unvalidated payloads as `unknown` and validate at the boundary. A generated client may retain its declared type when it also enforces the contract at runtime.
- `localStorage` / `sessionStorage`: handle `string | null`; treat parsed data as `unknown` until validated.
- URL parameters: handle the router or platform's nullable string shape, then parse and validate before converting to a domain type.
- Exported APIs and important boundaries: declare return types; allow inference for local implementations when the contract remains clear.

**Type Complexity Review Signals**

Use these as review prompts, not pass/fail thresholds. Existing project conventions and the component's responsibility take precedence.

- Props count: review ownership or splitting above 10.
- Optional props: review defaults or ownership when more than half are optional.
- Nested prop structures: review flattening beyond 2 levels.
- Type assertions: review the boundary when 3+ assertions are required.
- External API types: represent the actual external shape and convert at the application boundary.

## Coding Conventions

**Component and File Decisions**

- Prefer function components and Hooks for new code. Preserve working class components unless the accepted work requires migration; a class remains valid for an Error Boundary implementation.
- Reuse logic through the repository's established component, hook, or module pattern.
- Follow the project's adopted component architecture and file layout. Co-locate files only when it is established or approved as a new structure.

**Server/Client Boundary — only for RSC frameworks**

- Fetch and render on the server by default; isolate interactivity behind the smallest `"use client"` boundary that needs it.
- Keep browser-only APIs and event handlers inside client components.
- Skip these rules when the project has no server-component runtime.

**State Ownership**

- Preserve the repository's existing local, shared, and server-state ownership boundaries.
- Introduce Context, a shared-state layer, or a server-state dependency only when the accepted design requires ownership or lifecycle that the existing boundary cannot represent.
- Keep one authoritative owner for each state value and use immutable updates required by React change detection.

**Function and Props Boundaries**

- Prefer 0-2 parameters. For 3+ related values, use an object when it clarifies names or represents one domain input; preserve positional parameters when the repository convention or external API requires them.
- Declare component dependencies through typed props, hooks, Context, or injected modules according to the repository's established state and dependency boundaries.

**Environment Variables**

- Read client-side environment variables through the project's bundler accessor and public prefix.
- Validate required values through the repository's typed config layer; add a default only for an optional value or an explicitly defined local-development mode.

**Client Security**

- Keep credentials and secrets on the server; browser-delivered code and public environment variables are observable by clients.
- Exclude local environment files from version control and keep error output free of sensitive values.

**Asynchronous Processing**

- Follow the repository's promise style; use `async`/`await` when it clarifies sequencing and error propagation.
- Handle event-handler and asynchronous failures at their owning boundary. Error Boundaries cover descendant rendering failures, not ordinary callbacks or asynchronous work.
- Guard effect-driven requests against stale or post-unmount updates through the repository's cancellation or server-state mechanism.

**Formatting**

- Follow the repository's formatter, naming, module-resolution, and package-boundary configuration.
- Use an import alias only when the project configuration resolves it.

## Error Handling

Every caught error has one intentional outcome: propagate it, convert it to the repository's typed boundary result, or represent it as user-facing error state. Preserve context and log once at the boundary that owns diagnosis or recovery, with sensitive data redacted.

- Error Boundary: place it where descendant render failures have a defined UI recovery outcome.
- Custom Hook: preserve the application's existing error contract.
- API Layer: convert transport failures to the repository's established domain or boundary representation.
- Event handlers and async workflows: use the owning layer's exception, result, or UI-state contract.

## Performance Optimization

- When React Compiler is enabled, rely on it. Add manual `React.memo`, `useMemo`, or `useCallback` only for a measured bottleneck or a required stable identity at an external API/effect boundary.
- Apply code splitting or import changes when a configured bundle budget regresses, or when the accepted task names bundle size as an outcome and a repository bundle report attributes the relevant increase to the changed import. Follow the repository's existing loading pattern and verify the same signal after the change.

## Non-functional Requirements

- **Browser Compatibility**: Implement against the support policy in the PRD, Design Doc, Browserslist, or build configuration. When none is defined, preserve the repository's current transpilation/polyfill baseline and surface any new browser-dependent API as an unresolved compatibility decision.
- **Performance**: Verify against project-defined budgets and the metric representing the affected experience. When no budget exists, measure the changed path and report the observed result instead of inventing a threshold.

© shinpr · MIT · shinpr/claude-code-workflows

Similar skills

All skills for Frontend and UI →

From the same set43

The whole set →
testing-principles testing-principles — a skill for Claude Code enforces language-agnostic guidelines for test selection, mock boundaries, and assertion design. Triggers when writing new tests, planning test scope, or reviewing test suites. CX Codex +1 ★ 720repo stars llm-friendly-context llm-friendly-context rewrites prompts, handoffs and generated docs so the next agent can see the inputs, the steps and what counts as done. Useful whenever text goes to another model. CX Codex +1 ★ 720repo stars requirement-convergence requirement-convergence — a Claude Code skill that isolates a project outcome from proposed requirements and records user-stated exclusions. Runs at requirement intake before any system design begins. CX Codex +1 ★ 720repo stars work-planner The work-planner Claude Code subagent turns approved Design Docs into implementation plans with tasks, dependencies, and checks. It activates for work-plan or task-planning requests. CX Codex ★ 720repo stars documentation-criteria The documentation-criteria Claude Code skill selects the documents a change needs and determines where they belong. It activates for documentation planning and when creating or reviewing a technical document. CX Codex +1 ★ 720repo stars codebase-analyzer codebase-analyzer — a Claude Code subagent that inspects repository facts before creating a Design Doc. Runs on an approved PRD path or verbatim requirements to surface reuse, contract impacts, and risks. CX Codex ★ 720repo stars code-verifier The code-verifier Claude Code subagent checks claims in PRDs, design docs, and work plans against repository evidence. Run it before document review, after implementation, or to verify a description of an existing system. CX Codex ★ 720repo stars scope-discoverer scope-discoverer discovers functional scope across existing codebases for reverse documentation. Groups features into PRD-ready units. CX Codex ★ 720repo stars

Project sponsors

Companies that keep this analytics open