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

busirocket-typescript-standards skill

This skill enforces TypeScript/React standards for maintainable code, guiding one export per file, typed shapes, and Next.js special-file practices.

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

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

Files (12)

SKILL.md

2.5 KB

---
name: busirocket-typescript-standards
description:
  TypeScript 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

## Related Skills

- `busirocket-core-conventions` - General file structure (one-thing-per-file,
  boundaries)
- `busirocket-react` - Component and hook structure
- `busirocket-refactor-workflow` - Refactoring workflow for TypeScript/React

## 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 to keep codebases maintainable, predictable, and easy to review. It enforces one-export-per-file, strict type placement, naming conventions, and Next.js special-file exceptions. Use it as a checklist and automated rule set when creating or refactoring .ts/.tsx sources.

How this skill works

The skill inspects source layout and type usage rules, flags inline types, multiple exported symbols, and helper placement that violate conventions. It documents targeted rule files for each policy (one-thing-per-file, type placement, Next.js exceptions) and recommends running project checks after changes. Rules include explicit exceptions for Next.js special files and guidance for shared types under a types/ directory.

When to use it

Writing new .ts or .tsx files to ensure consistent structure and naming
Refactoring components, hooks, services, or route handlers to move types out
Adding shared shapes that should live under types/<area>/ with one type per file
Working on a Next.js app where special files need controlled extra exports
Before pull requests to validate exports, type placement, and project checks

Best practices

Export exactly one symbol per module you author to reduce coupling and improve discoverability
Place shared interfaces and types in types/<area>/ and keep one type per file
Avoid barrel index.ts files that hide module boundaries and make dependencies implicit
Do not declare inline interface/type in components, hooks, utils, services, or route handlers
After meaningful changes, run the project's verification command (e.g. yarn check:all)

Example use cases

Refactor a component that currently defines prop types inline into a types/Props file
Audit a codebase to remove index.ts barrels and make module boundaries explicit
Implement API route handlers in Next.js while allowing required method exports in app/api/**/route.ts
Create a shared Result type for service boundaries and keep it in its own file with a Result suffix
Enforce naming patterns like Params, Result, Error, and Props across a feature area

FAQ

What counts as a "special file" in Next.js?

Special files include app/**/page.tsx, app/**/layout.tsx and app/api/**/route.ts; these are allowed controlled extra exports like default export, metadata helpers, or HTTP method handlers.

Can I keep small helper functions next to a component?

Helpers that are purely presentational and tiny can live near a component, but business logic helpers should be extracted into their own modules to follow the one-thing-per-file rule.