TypeScript Best Practices
npx machina-cli add skill hoangnguyen0403/agent-skills-standard/best-practices --openclawTypeScript Best Practices
Priority: P1 (OPERATIONAL)
Implementation Guidelines
- Naming: Classes/Types=
PascalCase, vars/funcs=camelCase, consts=UPPER_SNAKE. PrefixIonly if needed. - Functions: Arrows for callbacks; regular for exports. Always type public API returns.
- Modules: Named exports only. Import order: external → internal → relative.
- Async: Use
async/await, not raw Promises.Promise.all()for parallel. - Classes: Explicit access modifiers. Favor composition. Use
readonly. - Types: Use
neverfor exhaustiveness,assertsfor runtime checks. - Optional: Use
?:, not| undefined. - Imports: Use
import typefor tree-shaking.
Anti-Patterns
- No Default Exports: Use named exports.
- No Implicit Returns: Specify return types.
- No Unused Variables: Enable
noUnusedLocals. - No
require: Use ES6import. - No Empty Interfaces: Use
typeor non-empty interface. - Use any: Never use
any, useunknownonly when necessary.
Reference & Examples
See references/examples.md for code samples including:
- Immutable Interfaces
- Exhaustiveness Checking
- Assertion Functions
- Dependency Injection Patterns
- Import Organization
Related Topics
language | tooling | security
Source
git clone https://github.com/hoangnguyen0403/agent-skills-standard/blob/develop/.github/skills/typescript/best-practices/SKILL.mdView on GitHub Overview
Provides concrete, idiomatic TypeScript patterns to keep code readable and maintainable. It covers naming conventions, module exports, async handling, and type-level safeguards, and highlights anti-patterns to avoid. The guidance helps teams enforce a consistent TS approach across projects.
How This Skill Works
Code follows explicit rules: naming conventions, arrow-based callbacks, and explicit public API return types. It enforces module structure with named exports and a consistent import order, prioritizes async/await with Promise.all for parallelism, and embraces strong typing (readonly, never, asserts) and safe optionals. It also promotes import.type usage for tree-shaking and forbids default exports and any.
When to Use It
- When starting a TypeScript project and defining code conventions
- During code reviews to enforce consistent patterns
- When designing public APIs and library interfaces
- When refactoring to modern TS patterns (async/await, exports, typings)
- When migrating from JavaScript to TypeScript and enabling safer types
Quick Start
- Step 1: Audit code for naming conventions and type annotations (classes PascalCase, vars/functions camelCase, consts UPPER_SNAKE).
- Step 2: Refactor modules to named exports; add explicit return types for public APIs; use import type where appropriate.
- Step 3: Adopt async/await with Promise.all for parallel tasks; enable TS strict checks (noUnusedLocals, etc.).
Best Practices
- Naming and typing: Classes/Types PascalCase, vars/functions camelCase, consts UPPER_SNAKE; prefix I only when needed.
- Public API: Use explicit return types and arrow callbacks where appropriate.
- Modules and imports: Use named exports only; organize imports externally → internal → relative; use import type for tree-shaking.
- Async patterns: Prefer async/await; avoid raw Promises; use Promise.all() for parallel work.
- Types and safety: Use readonly where possible; never for exhaustiveness; use asserts for runtime checks; avoid any; prefer unknown when necessary; avoid default exports and empty interfaces.
Example Use Cases
- Immutable Interfaces
- Exhaustiveness Checking
- Assertion Functions
- Dependency Injection Patterns
- Import Organization
