home / skills / busirocket / agents-skills / busirocket-typescript-react-standards

busirocket-typescript-react-standards skill

safe

/skills/busirocket-typescript-react-standards

This skill enforces TypeScript and React standards for maintainable TS/TSX code, promoting one-export-per-file and strict typing across Next.js projects.

npx playbooks add skill busirocket/agents-skills --skill busirocket-typescript-react-standards

Review the files below or copy the command above to add this skill to your agents.

Files (12)

SKILL.md

2.3 KB

---
name: busirocket-typescript-react-standards
description:
  TypeScript and React standards for maintainable codebases. Use when creating
  or refactoring TS/TSX to enforce one-thing-per-file, type conventions, and
  Next.js special-file export exceptions.
metadata:
  author: cristiandeluxe
  version: "1.0.0"
---

# TypeScript + React Standards

Strict, reusable standards for TypeScript/React projects.

## When to Use

Use this skill when:

- Writing or refactoring `.ts` / `.tsx`
- Moving inline types into `types/`
- Enforcing consistent type naming and result shapes
- Working in Next.js where special files allow extra exports

## Non-Negotiables (MUST)

- **One exported symbol per file** for your own modules.
- **No inline `interface`/`type`** in components/hooks/utils/services/route
  handlers.
- Put shared shapes under `types/<area>/...` (**one type per file**).
- Avoid barrel files (`index.ts`) that hide dependencies.
- After meaningful changes: run the project's standard checks (e.g.
  `yarn check:all`).

## Next.js Special-file Exceptions

- `app/**/page.tsx`, `app/**/layout.tsx`: allow `default export` +
  `metadata/generateMetadata/viewport` (etc.).
- `app/api/**/route.ts`: allow multiple HTTP method exports and route config
  exports.

## Rules

### TypeScript Standards

- `ts-language-style` - Language & style (interface vs type, const vs let,
  English-only)
- `ts-one-thing-per-file` - One thing per file (STRICT)
- `ts-nextjs-exceptions` - Next.js special-file exceptions
- `ts-types-strict` - Types (STRICT) - no inline types
- `ts-helpers-strict` - Helpers (STRICT) - no helpers in components/hooks
- `ts-nextjs-hygiene` - Next.js TS hygiene (docs-aligned)
- `ts-validation` - Validation (run checks after changes)

### Types Conventions

- `types-one-type-per-file` - One type per file (STRICT)
- `types-naming-patterns` - Naming patterns (Params, Result, Error, Props)
- `types-result-shape` - Result shape for boundaries that can fail
- `types-where-allowed` - Where types are allowed

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/ts-one-thing-per-file.md
rules/ts-types-strict.md
rules/types-one-type-per-file.md
```

Each rule file contains:

- Brief explanation of why it matters
- Code examples (correct and incorrect patterns)
- Additional context and best practices

Overview

This skill defines strict TypeScript and React standards for maintainable codebases. It enforces one-thing-per-file, consistent type naming, and Next.js special-file export exceptions. Use it to keep types, components, and helpers predictable and easy to navigate during development or refactors.

How this skill works

The skill inspects .ts/.tsx files and validates file-level rules such as one exported symbol per module and no inline type or interface declarations in components, hooks, utilities, services, or route handlers. It recognizes Next.js special-file locations and allows documented exceptions (page/layout defaults and API route method exports). Rule files explain intent, show correct/incorrect samples, and link to required checks to run after changes.

When to use it

Creating or refactoring .ts and .tsx files in a TypeScript React or Next.js project
Moving inline types into a shared types/ directory to improve reuse and discoverability
Enforcing consistent type naming and standardized result shapes across boundaries
Working on Next.js app routes and pages where framework exceptions apply
Running project hygiene or validation after meaningful changes

Best practices

Keep exactly one exported symbol per file for your own modules to simplify imports and reviews
Place shared shapes under types/<area>/ with one type per file and clear naming (Params, Result, Error, Props)
Avoid barrel index.ts files that can hide real dependencies and complicate refactoring
Never declare inline interface or type inside components, hooks, utilities, services, or route handlers
Run the project’s standard checks (for example yarn check:all) after meaningful changes

Example use cases

Refactor a component that contains inline request/response types by moving those types into types/ui/ComponentResult.ts
Migrate a monolithic utils file into single-export helper modules to comply with one-thing-per-file
Validate a Next.js app/page that must export a default component and metadata without breaking rules
Apply uniform Result/ResultError shapes at API boundaries to ensure consistent error handling
Audit a codebase to remove barrel exports and make dependency edges explicit

FAQ

What counts as a special-file exception in Next.js?

Common exceptions include app/**/page.tsx and app/**/layout.tsx allowing a default export plus metadata helpers, and app/api/**/route.ts allowing multiple HTTP method exports and route config exports.

Why one exported symbol per file?

One export per file makes intent explicit, simplifies imports, reduces accidental coupling, and speeds code reviews and refactors.

Where should I put a small helper used only by one component?

If truly private to the component, keep it local but avoid placing type declarations inline; prefer moving any shared types to types/ and keep helpers separate from component logic when possible.