clean-code-ts-react

name

clean-code-ts-react

description

Use when writing, reviewing, or refactoring TypeScript or React code for craftsmanship — naming, function and component shape, error handling, data modeling, tests, and abstraction. Translates Robert C. Martin's Clean Code principles into modern TS+React idioms (TS 5.x, React 19), with first-class "When NOT to apply" guidance and a Meta category for principle conflicts (DRY vs SRP, small functions vs deep modules, type safety vs ergonomics). Triggers on code review, refactoring for clarity, naming, function/component design, "is this clean?", "make this more readable", "right abstraction?" — even when the user doesn't say "clean code". Does NOT cover React-specific APIs (RSC, hooks API surface) — use the `react` skill. Does NOT cover TS compiler perf or tsconfig — use the `typescript` skill.

Robert C. Martin (Uncle Bob) TypeScript 5.x + React 19 Best Practices

Craftsmanship principles from Robert C. Martin's Clean Code (2008), re-expressed for modern TypeScript and React. Contains 61 rules across 11 categories, prioritized by cognitive cost across a code change's lifetime. Examples use TS 5.x and React 19 idioms — but the rules are about timeless principles, not specific APIs.

What Makes This Skill Different

Three things set this apart from a generic clean-code copy:

1. Modern idioms as vehicle. Examples use TS 5.x (satisfies, branded types, discriminated unions, const type parameters) and React 19 (function components, hooks, use(), Server Components where relevant). But the rule is always the principle, never the syntax.
2. "When NOT to apply" is first-class. Every rule has 2-3 concrete scenarios where the principle should bend — not generic disclaimers, real situations. Loop counters can be i. Single-use code shouldn't be DRY. Some HOCs are unavoidable.
3. Meta category for principle conflicts. Category 11 names the most common tensions explicitly — DRY vs Single Responsibility, small functions vs deep modules (Ousterhout), type precision vs ergonomic APIs, tests as spec vs documentation. The mark of seniority is knowing which to bend.

When to Apply

Reference these guidelines when:

• Writing new TypeScript or React code and wanting craftsmanship feedback
• Reviewing a pull request for clarity, naming, or abstraction
• Refactoring existing code for readability or maintainability
• Designing function, hook, or component APIs
• Deciding whether to extract, abstract, or duplicate
• Resolving a tension between two clean-code rules (see Category 11)

Skip this skill and use:

• react for React 19 API patterns (concurrent rendering, Server Components, ref-as-prop, useActionState, <Context>-as-provider)
• typescript for compiler performance, tsconfig tuning, type-system perf
• refactor for mechanical refactoring workflows
• tdd for the TDD workflow itself

Rule Categories by Priority

Order reflects cognitive cost across a change's lifetime (read → understand → modify → verify → ship → maintain). Earlier stages cascade — bad names taint every read.

Priority	Category	Impact	Prefix	Rules
1	Meaningful Names	CRITICAL	name-	8
2	Functions, Components & Hooks	CRITICAL	func-	8
3	Self-Documentation (Types & Comments)	HIGH	doc-	5
4	Formatting (Beyond Prettier)	HIGH	fmt-	4
5	Error Handling	HIGH	err-	7
6	Data Shape & Immutability	MEDIUM-HIGH	data-	6
7	Boundaries	MEDIUM-HIGH	bound-	4
8	Composition over Inheritance	MEDIUM-HIGH	comp-	6
9	Tests	MEDIUM	test-	5
10	Emergence & Simple Design	MEDIUM	emerge-	4
11	Meta: When Principles Conflict	MEDIUM	meta-	4

Total: 61 rules.

Quick Reference

1. Meaningful Names (CRITICAL)

• name-intention-revealing — Use names that reveal intent
• name-avoid-disinformation — Avoid misleading names
• name-meaningful-distinctions — Make meaningful distinctions
• name-component-pascal-case — Components are PascalCase noun phrases
• name-hook-use-prefix — Hooks are useX verb phrases
• name-handler-convention — Event handlers use onX / handleX
• name-boolean-predicate — Boolean variables use is/has/can
• name-types-pascal-case — Types and interfaces are PascalCase

2. Functions, Components & Hooks (CRITICAL)

• func-small — Keep functions, components & hooks small
• func-one-thing — Do one thing
• func-abstraction-level — One level of abstraction per function
• func-minimize-arguments — Prefer object parameters over long lists
• func-no-side-effects — Avoid hidden side effects (especially in render)
• func-command-query-separation — Separate commands from queries
• func-dry — DRY — until concepts diverge
• func-custom-hook-extract — Extract custom hooks for reusable stateful logic

3. Self-Documentation: Types & Comments (HIGH)

• doc-types-over-comments — Prefer types over comments
• doc-satisfies-narrows-with-check — Use satisfies for inferred-but-checked values
• doc-jsdoc-public-api — JSDoc for public APIs and non-obvious side effects
• doc-avoid-redundant-comments — Avoid redundant comments
• doc-delete-commented-out-code — Delete commented-out code

4. Formatting Beyond Prettier (HIGH)

• fmt-vertical-density — Keep related code close, unrelated far
• fmt-newspaper-order — Order files top-down like a newspaper
• fmt-team-rules-over-preference — Team conventions over personal preference
• fmt-imports-grouped — Group imports by source

5. Error Handling (HIGH)

• err-early-return — Use early returns to flatten error paths
• err-result-vs-throw — Choose throw vs Result deliberately
• err-narrow-unknown — Always narrow unknown in catch blocks
• err-error-boundaries — Use error boundaries for render-time failures
• err-suspense-for-loading — Use Suspense for loading states
• err-no-swallow — Never swallow errors silently
• err-null-vs-undefined — Pick null OR undefined per domain

6. Data Shape & Immutability (MEDIUM-HIGH)

• data-discriminated-unions-over-flags — Discriminated unions over boolean flags
• data-readonly-by-default — Mark read-only data readonly
• data-branded-types — Brand types for domain invariants
• data-dto-vs-domain — Separate DTOs from domain types
• data-demeter-prop-drilling — Prop drilling often smells like Demeter
• data-structural-typing-pitfalls — Beware structural typing aliasing

7. Boundaries (MEDIUM-HIGH)

• bound-wrap-third-party-hooks — Wrap third-party hooks in custom hooks
• bound-learning-tests — Write learning tests for third-party behavior
• bound-isolate-framework — Isolate framework-specific code at the edges
• bound-type-assertions-at-edges — Type assertions belong only at boundaries

8. Composition over Inheritance (MEDIUM-HIGH)

• comp-children-over-props — Compose with children over configuration props
• comp-small-components — Keep components small and cohesive
• comp-avoid-hoc-stacks — Avoid higher-order component stacks
• comp-context-only-when-needed — Context for DI, not prop avoidance
• comp-render-props-vs-hooks — Prefer hooks over render props for logic reuse
• comp-separate-construction-from-use — Separate setup from rendering

9. Tests (MEDIUM)

• test-behavior-not-implementation — Test behavior, not implementation
• test-mock-at-boundaries — Mock only at true boundaries
• test-first-principles — Apply FIRST principles
• test-one-concept — One concept (not one assert) per test
• test-clean-as-production — Test code deserves production-grade care

10. Emergence & Simple Design (MEDIUM)

• emerge-four-rules — Apply the four rules of simple design in order
• emerge-yagni-types — Avoid premature type generics
• emerge-premature-abstraction — Resist premature abstraction
• emerge-reveal-intent — Maximize expressiveness — code as communication

11. Meta: When Principles Conflict (MEDIUM)

This is the signature category — explicit guidance on when one clean-code principle yields to another.

• meta-dry-vs-srp — Bend DRY when concepts drift apart
• meta-small-vs-deep — Small functions lose to deep modules when indirection > comprehension
• meta-types-vs-ergonomics — Type safety loses to ergonomics at stable boundaries
• meta-tests-as-spec-vs-doc — Pick tests-as-spec or tests-as-documentation per file

How to Use

For an ad-hoc question ("is this naming OK?", "should I extract this?"), jump straight to the relevant rule file via the Quick Reference above.

For a code review or refactor, scan the categories in priority order — names and function shape first (highest cascade), then errors and data shape, then composition and tests. The category-major sweep is more efficient than file-major.

When two principles seem to disagree, read the corresponding Meta rule (Category 11). Pick the principle that wins, and document the call.

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for adding new rules
metadata.json	Version and reference information

Related Skills

• .experimental/clean-code — Original language-agnostic clean code (Java examples). This skill is the TS+React sibling.
• .curated/react — React 19-specific patterns (Server Components, concurrent rendering, ref-as-prop).
• .curated/typescript — TS compiler performance and tsconfig tuning.
• .curated/refactor — Mechanical refactoring workflows.
• .curated/tdd — The TDD workflow itself.