JavaScript and TypeScript Best Practices

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

When to Activate This Skill

Use this skill when the task involves:

Writing JavaScript/TypeScript Code

• Creating new functions, classes, or modules
• Implementing control flow logic (conditionals, loops, early returns)
• Managing state with variables (

  const

  vs

  let

  )
• Writing TypeScript type definitions, interfaces, or generics
• Defining enums or constant objects
• Structuring code with proper naming conventions

TypeScript-Specific Tasks

• Fixing type errors or improving type safety
• Replacing

  any

  with proper types (

  unknown

  , generics)
• Converting

  enum

  to

  as const

  objects
• Choosing between

  type

  and

  interface

• Adding type annotations to untyped code
• Implementing generic functions or utilities

Code Quality & Style

• Refactoring nested conditionals to early returns
• Simplifying complex control flow
• Improving variable naming (descriptive names, proper prefixes for booleans)
• Reducing code duplication
• Applying consistent code style
• Removing commented-out code or outdated comments

Safety & Validation

• Adding input validation at system boundaries
• Implementing assertions for programmer error detection
• Improving error handling patterns
• Writing better error messages (user-facing or developer-facing)
• Validating external data with schemas (Zod, etc.)
• Preventing null/undefined propagation

Performance Optimization

• Reducing unnecessary branching or conditionals
• Optimizing array operations (reduce instead of chained filter/map)
• Implementing efficient data structures (Set vs Array for lookups)
• Caching expensive computations or API calls
• Optimizing loops (cache property access, array length)
• Deferring

  await

  operations to avoid blocking
• Caching

  localStorage

  ,

  sessionStorage

  , or cookie reads

Documentation

• Adding JSDoc comments to exported functions
• Using proper comment markers (TODO, FIXME, HACK, NOTE, PERF)
• Removing unnecessary comments
• Preserving important comments (business logic, linter directives)
• Documenting function parameters, return types, and examples

Code Review

• Reviewing code for style violations
• Identifying performance anti-patterns
• Checking for safety issues (missing validation, poor error handling)
• Ensuring TypeScript best practices
• Verifying proper documentation

When NOT to Use This Skill

Do not activate for:

• Framework-specific code (React, Vue, Angular) - use framework-specific skills instead
• Node.js-specific APIs or server-side concerns (unless general JS/TS patterns apply)
• Build tooling configuration (webpack, vite, tsconfig.json) unless code quality-related
• Testing code (use a testing-specific skill if available)
• Database queries or ORM usage
• CSS, HTML, or styling (unless embedded in JS/TS files)
• Package management (npm, yarn, pnpm)

How to Use

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

1. Start with the Overview (AGENTS.md)

Read 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:

General Best Practices:

• naming-conventions.md - Descriptive names, qualifier ordering, boolean prefixes
• functions.md - Function size, parameters, explicit values
• control-flow.md - Early returns, flat structure, block style
• state-management.md - const vs let, immutability, pure functions
• return-values.md - Return zero values instead of null/undefined
• misc.md - Line endings, defensive programming, technical debt

TypeScript:

• any.md - Avoid any, use unknown or generics
• enums.md - Use as const objects instead of enum
• type-vs-interface.md - Prefer type over interface

Safety:

• input-validation.md - Validate external data with schemas
• assertions.md - Split assertions, include values
• error-handling.md - Handle all errors explicitly
• error-messages.md - User-friendly vs developer-specific messages

Performance:

• reduce-branching.md - Use lookup tables instead of conditionals
• reduce-looping.md - reduce vs chained methods, Set.has() vs Array.includes()
• memoization.md - When to memoize (avoid trivial computations)
• batching.md - Batch I/O operations
• predictable-execution.md - Clear execution paths for CPU caching
• bounded-iteration.md - Set limits on loops and queues
• defer-await.md - Move await into branches that need it
• cache-property-access.md - Cache object lookups in loops
• cache-storage-api.md - Cache localStorage/sessionStorage/cookie reads

Documentation:

• jsdoc.md - Well-formed JSDoc for exports
• comment-markers.md - TODO, FIXME, HACK, NOTE markers
• comments-to-remove.md - Commented code, edit history
• comments-to-preserve.md - Markers, linter directives, business logic
• comments-placement.md - Move end-of-line comments above code

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

Examples

Example 1: Optimizing Array Operations

Task: "This filter().map() chain is slow on large arrays"

Approach:

1. Read AGENTS.md overview
2. Identify issue: multiple iterations over same array
3. Load reduce-looping.md
4. Replace chained methods with single reduce() call

Before:

const result = items.filter(x => x.active).map(x => x.id);

After:

const result = items.reduce((acc, x) =>
  x.active ? [...acc, x.id] : acc,
  []
);

Example 2: Fixing TypeScript

any

Usage

Task: "Replace

any

types with proper TypeScript types"

Approach:

1. Read AGENTS.md overview
2. Identify need for type safety
3. Load any.md
4. Replace

   any

   with

   unknown

   or generics based on use case

Before:

function process(data: any): any { /**/ }

After:

function process<T>(data: T): Result<T> { /**/ }
// or
function process(data: unknown): User { /**/ }

Example 3: Improving Error Messages

Task: "Make error messages more helpful for users"

Approach:

1. Read AGENTS.md overview
2. Identify need for better error messaging
3. Load error-messages.md
4. Replace technical errors with user-friendly, actionable messages

Before:

throw new Error('500');

After:

alert(
  'We\'re having trouble connecting to our server.\n' +
  'Please check your internet connection and try again.'
);

Example 4: Caching Storage API Calls

Task: "This function calls localStorage.getItem() 100 times in a loop"

Approach:

1. Read AGENTS.md overview
2. Identify performance issue: repeated storage reads
3. Load cache-storage-api.md
4. Implement Map-based cache with invalidation strategy

Before:

for (const item of items) {
  const theme = localStorage.getItem('theme');
  // ... 100 storage reads
}

After:

const storageCache = new Map();
function getCached(key) {
  if (!storageCache.has(key)) {
    storageCache.set(key, localStorage.getItem(key));
  }
  return storageCache.get(key);
}

for (const item of items) {
  const theme = getCached('theme');
  // ... 1 storage read
}

Important Notes

Performance Philosophy

Design for performance from the start. Optimize slowest resources first:

network >> disk >> memory >> cpu

Always benchmark your assumptions before moving on. Premature optimization of CPU-bound operations while ignoring network bottlenecks wastes time.

State Management Principles

• Prefer

  const

  : Use

  let

  only for valid performance reasons
• Immutability: Never mutate passed references; create copies
• Pure functions: Keep leaf functions pure; centralize state in parents
• Zero values: Return

  []

  ,

  {}

  ,

  0

  ,

  ''

  instead of

  null

  /

  undefined

TypeScript Best Practices

• Avoid

  any

  : Use

  unknown

  for truly unknown types, generics for flexibility
• Avoid

  enum

  : Use

  as const

  objects for better tree-shaking and type inference
• Prefer

  type

  : Use

  interface

  only for declaration merging or class contracts

Code Quality Principles

• Functions under 50 lines: Break down large functions
• Early returns: Prefer flat control flow over nested conditionals
• Descriptive names: Use complete words, append qualifiers in descending order
• Explicit values: Avoid default parameters; make all values explicit at call site

Safety First

• Validate at boundaries: All external data must be validated (user input, API responses)
• Assertions for programmer errors: Crash on corrupted code state
• Split compound assertions: One assertion per invariant
• Include values in messages: Always show actual vs expected values

Documentation Standards

• All exports need JSDoc: Minimum

  @param

  ,

  @returns

  ,

  @example

• Use comment markers: TODO, FIXME, HACK, NOTE, REVIEW, PERF
• Remove dead code: No commented-out code or edit history
• Preserve business logic: Keep comments explaining "why", not "what"

Optimization Strategies

When optimizing performance:

1. Measure first: Use profiling tools to identify actual bottlenecks
2. Network first: Optimize network requests before code execution
3. Reduce iterations: Single reduce() instead of chained filter().map()
4. Cache lookups: Use Set for O(1) membership checks, cache property access in loops
5. Defer work: Move expensive operations (await, computation) into branches that need them
6. Batch operations: Group I/O operations to reduce overhead
7. Predictable paths: Write code with clear execution flow for CPU optimization

Additional Context

When Functions Are Too Small

Some patterns (like lookup tables) may seem to violate the "no premature optimization" principle. These are architectural choices, not optimizations:

• Lookup tables improve maintainability (add entries without new conditionals)
• Early returns reduce cognitive load (fewer nested levels)
• Const over let prevents accidental mutations (correctness, not speed)

Defensive Programming

This skill emphasizes "negative-space" or defensive programming:

• Return zero values to eliminate downstream null checks
• Assert invariants to catch bugs early
• Validate at boundaries to contain invalid data
• Handle all errors explicitly (no silent failures)

The goal is correctness first, performance second.