home / skills / gohypergiant / agent-skills / accelint-ts-best-practices

accelint-ts-best-practices skill

safe

This skill enforces TypeScript and JavaScript best practices to improve type safety, readability, and maintainability across codebases.

npx playbooks add skill gohypergiant/agent-skills --skill accelint-ts-best-practices

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

Files (20)

SKILL.md

4.6 KB

---
name: accelint-ts-best-practices
description: Comprehensive TypeScript/JavaScript coding standards focusing on type safety, defensive programming, and code correctness. Use when (1) Writing or reviewing TS/JS code, (2) Fixing type errors or avoiding any/enum/null, (3) Implementing control flow, state management, or error handling, (4) Applying zero-value pattern or immutability, (5) Code review for TypeScript anti-patterns. Covers naming conventions, function design, return values, bounded iteration, input validation. For performance optimization, use accelint-ts-performance skill. For documentation, use accelint-ts-documentation skill.
license: Apache-2.0
metadata:
  author: accelint
  version: "1.1"
---

# JavaScript and TypeScript Best Practices

Comprehensive coding standards for JavaScript and TypeScript applications, designed for AI agents and LLMs working with modern JavaScript/TypeScript codebases.

**Note:** This skill focuses on general best practices, TypeScript patterns, and safety. For performance optimization, use the `accelint-ts-performance` skill instead.

## When to Use This Skill

This skill provides expert-level patterns for JavaScript and TypeScript code. Load [AGENTS.md](AGENTS.md) to scan rule summaries and identify relevant optimizations for your task.

## How to Use

This skill uses a **progressive disclosure** structure to minimize context usage:

### 1. Start with the Overview (AGENTS.md)
Read [AGENTS.md](AGENTS.md) for a concise overview of all rules with one-line summaries organized by category.

### 2. Load Specific Rules as Needed
When you identify a relevant pattern or issue, load the corresponding reference file for detailed implementation guidance:

**Quick Start:**
- [quick-start.md](references/quick-start.md) - Complete workflow examples with before/after code

**General Best Practices:**
- [naming-conventions.md](references/naming-conventions.md) - Descriptive names, qualifier ordering, boolean prefixes
- [functions.md](references/functions.md) - Function size, parameters, explicit values
- [control-flow.md](references/control-flow.md) - Early returns, flat structure, block style
- [state-management.md](references/state-management.md) - const vs let, immutability, pure functions
- [return-values.md](references/return-values.md) - Return zero values instead of null/undefined
- [misc.md](references/misc.md) - Line endings, defensive programming, technical debt
- [code-duplication.md](references/code-duplication.md) - Extract common patterns, DRY principle, when to consolidate

**TypeScript:**
- [any.md](references/any.md) - Avoid any, use unknown or generics
- [enums.md](references/enums.md) - Use as const objects instead of enum
- [type-vs-interface.md](references/type-vs-interface.md) - Prefer type over interface

**Safety:**
- [input-validation.md](references/input-validation.md) - Validate external data with schemas
- [assertions.md](references/assertions.md) - Split assertions, include values
- [error-handling.md](references/error-handling.md) - Handle all errors explicitly
- [error-messages.md](references/error-messages.md) - User-friendly vs developer-specific messages

**Performance:**
- **For performance optimization tasks**, use the `accelint-ts-performance` skill for comprehensive profiling workflows and optimization patterns

**Documentation:**
- **For documentation tasks**, use the `accelint-ts-documentation` skill for comprehensive JSDoc and comment guidance

### 3. Apply the Pattern
Each reference file contains:
- ❌ Incorrect examples showing the anti-pattern
- ✅ Correct examples showing the optimal implementation
- Explanations of why the pattern matters

### 4. Use the Report Template
When this skill is invoked, use the standardized report format:

**Template:** [`assets/output-report-template.md`](assets/output-report-template.md)

The report format provides:
- Executive Summary with impact assessment
- Severity levels (Critical, High, Medium, Low) for prioritization
- Impact analysis (potential bugs, type safety, maintainability, runtime failures)
- Categorization (Type Safety, Safety, State Management, Return Values, Code Quality)
- Pattern references linking to detailed guidance in references/
- Phase 2 summary table for tracking all issues

**When to use the audit template:**
- Skill invoked directly via `/accelint-ts-best-practices <path>`
- User asks to "review code quality" or "audit code" across file(s), invoking skill implicitly

**When NOT to use the report template:**
- User asks to "fix this type error" (direct implementation)
- User asks "what's wrong with this code?" (answer the question)
- User requests specific fixes (apply fixes directly without formal report)

Overview

This skill provides comprehensive TypeScript and JavaScript coding standards that prioritize type safety, defensive programming, and code correctness. It codifies naming conventions, function design, return-value patterns, bounded iteration, input validation, and state management. Use it when writing or reviewing TS/JS code to avoid common anti-patterns such as any, unchecked nulls, and mutable shared state. For performance or documentation tasks, pair this skill with accelint-ts-performance or accelint-ts-documentation respectively.

How this skill works

The skill inspects code for anti-patterns and recommends concrete, idiomatic replacements (before/after examples). It focuses on type-level safety (prefer type over interface where appropriate, avoid any), control-flow clarity (early returns, flat blocks), and safe return values (zero-value instead of null/undefined). When invoked for audits it produces a standardized report with severity, impact analysis, and phase-2 tracking; for focused fixes it provides targeted code changes and explanations.

When to use it

Writing new TypeScript/JavaScript modules or refactoring existing ones
During code review to catch type-safety and defensive-programming issues
Fixing type errors and eliminating any, unsafe enums, or nullable return values
Implementing control flow, state management, or centralized error handling
Applying immutability, zero-value patterns, or reducing shared mutable state

Best practices

Prefer explicit types and narrow unions; use unknown or generics instead of any
Return zero-values (empty arrays/objects) rather than null/undefined for predictable callers
Favor small pure functions, limit parameter count, and avoid hidden side effects
Use early returns and flat control flow to reduce nesting and improve readability
Validate external input with schemas and split assertions with clear messages
Use const, immutability patterns, and pure state transitions to prevent bugs

Example use cases

Review a pull request to flag unsafe any usage and suggest typed alternatives
Convert functions that return null to returning empty collections or Option-like types
Refactor a stateful module to use immutable updates and explicit action handlers
Audit error handling to ensure all failure paths surface actionable developer messages
Enforce naming conventions and boolean-prefix rules across a codebase

FAQ

When should I avoid using this skill's report template?

Skip the full report template when the user requests a simple fix or asks what’s wrong with a specific code snippet; provide direct fixes instead.

Does this skill handle performance tuning?

No. Use accelint-ts-performance for profiling and performance-specific changes; this skill focuses on correctness and safety.