🇺🇸English

TypeScript Guidelines

Related Skills : See arktype for runtime type validation patterns. See typebox for TypeBox schema patterns. See testing for test file conventions.

When to Apply This Skill

Use this pattern when you need to:

• Write or refactor TypeScript code with project-wide naming and style conventions.
• Choose clear control-flow/value-mapping patterns for unions and discriminated values.
• Apply baseline TypeScript defaults before loading specialized sub-topic guidance.

References

Load these on demand based on what you're working on:

• If working with type placement and constants organization (types.ts location, co-location rules, options/IDs naming), read references/type-organization.md
• If working with factory-focused refactors (parameter destructuring, extracting coupled let state into sub-factories), read references/factory-patterns.md
• If working with arktype + branded IDs (optional property syntax, brand constructors, workspace table IDs), read references/runtime-schema-patterns.md
• If working with test writing and test file layout (inline single-use setup, source-shadowing tests), read references/testing-patterns.md
• If working with advanced TS/ES features (iterator helpers, const generic array inference), read references/advanced-typescript-features.md

Core Rules

• Always use type instead of interface in TypeScript.

• readonly only for arrays and maps: Never use readonly on primitive properties or object properties. The modifier is shallow and provides little protection for non-collection types. Use it only where mutation is a realistic footgun:

  // Good - readonly only on the array
  

  type Config = { version: number; vendor: string; items: readonly string[]; };

  // Bad - readonly everywhere is noise type Config = { readonly version: number; readonly vendor: string; readonly items: readonly string[]; };

Exception: Match upstream library types exactly (e.g., standard-schema interfaces). See docs/articles/readonly-is-mostly-noise.md for rationale.

• Acronyms in camelCase : Treat acronyms as single words, capitalizing only the first letter:

  // Correct - acronyms as words
  

  parseUrl(); defineKv(); readJson(); customerId; httpClient;

  // Incorrect - all-caps acronyms parseURL(); defineKV(); readJSON(); customerID; HTTPClient;

Exception: Match existing platform APIs (e.g., XMLHttpRequest). See docs/articles/acronyms-in-camelcase.md for rationale.

• TypeScript 5.5+ automatically infers type predicates in .filter() callbacks. Don't add manual type assertions:

  // Good - TypeScript infers the narrowed type automatically
  

  const filtered = items.filter((x) => x !== undefined);

  // Bad - unnecessary type predicate const filtered = items.filter( (x): x is NonNullable<typeof x> => x !== undefined, );

• When moving components to new locations, always update relative imports to absolute imports (e.g., change import Component from '../Component.svelte' to import Component from '$lib/components/Component.svelte')

• When functions are only used in the return statement of a factory/creator function, use object method shorthand syntax instead of defining them separately. For example, instead of:

  function myFunction() {
  const helper = () => {
  	/* ... */
  };
  return { helper };
  

  }

Use:

    function myFunction() {
	return {
		helper() {
			/* ... */
		},
	};
}

• Prefer factory functions over classes : Use function createX() { return { ... } } instead of class X { ... }. Closures provide structural privacy—everything above the return statement is private by position, everything inside it is the public API. Classes mix private/protected/public members in arbitrary order, forcing you to scan every member and check its modifier. See docs/articles/closures-are-better-privacy-than-keywords.md for rationale.

Boolean Naming: is/has/can Prefix

Boolean properties, variables, and parameters MUST use a predicate prefix that reads as a yes/no question:

• is — state or identity: isEncrypted, isLoading, isVisible, isActive

• has — possession or presence: hasToken, hasChildren, hasError

• can — capability or permission: canWrite, ,

This applies to:

• Object/type properties (isActive: boolean)
• Getter methods (get isEncrypted())
• Local variables (const isValid = ...)
• Function parameters (function toggle(isEnabled: boolean))
• Function return values when the function is a predicate (function isExpired(): boolean)

Exception: Match upstream library types exactly (e.g., tab.pinned, window.focused from APIs where the type is externally defined).

Switch Over If/Else for Value Comparison

When multiple if/else if branches compare the same variable against string literals (or other constant values), always use a switch statement instead. This applies to action types, status fields, file types, strategy names, or any discriminated value.

// Bad - if/else chain comparing the same variable
if (change.action === 'add') {
	handleAdd(change);
} else if (change.action === 'update') {
	handleUpdate(change);
} else if (change.action === 'delete') {
	handleDelete(change);
}

// Good - switch statement
switch (change.action) {
	case 'add':
		handleAdd(change);
		break;
	case 'update':
		handleUpdate(change);
		break;
	case 'delete':
		handleDelete(change);
		break;
}

Use fall-through for cases that share logic:

switch (change.action) {
	case 'add':
	case 'update': {
		applyChange(change);
		break;
	}
	case 'delete': {
		removeChange(change);
		break;
	}
}

Use block scoping ({ }) when a case declares variables with let or const.

When NOT to use switch: early returns for type narrowing are fine as sequential if statements. If each branch returns immediately and the checks are narrowing a union type for subsequent code, keep them as if guards.

See docs/articles/switch-over-if-else-for-value-comparison.md for rationale.

Record Lookup Over Nested Ternaries

When an expression maps a finite set of known values to outputs, use a satisfies Record lookup instead of nested ternaries. This is the expression-level counterpart to "Switch Over If/Else": switch handles statements with side effects, record lookup handles value mappings.

// Bad - nested ternary
const tooltip = status === 'connected'
	? 'Connected'
	: status === 'connecting'
		? 'Connecting…'
		: 'Offline';

// Good - record lookup with exhaustive type checking
const tooltip = ({
	connected: 'Connected',
	connecting: 'Connecting…',
	offline: 'Offline',
} satisfies Record<SyncStatus, string>)[status];

satisfies Record<SyncStatus, string> gives you compile-time exhaustiveness: if SyncStatus gains a fourth value, TypeScript errors because the record is missing a key. Nested ternaries silently fall through to the else branch.

as const is unnecessary here. satisfies already validates the shape and value types. as const would narrow values to literal types ('Connected' instead of string), which adds no value when the output is just rendered or passed as a string.

When the record is used once, inline it. When it's shared or has 5+ entries, extract to a named constant.

See docs/articles/record-lookup-over-nested-ternaries.md for rationale.

Weekly Installs

76

Repository

epicenterhq/epicenter

GitHub Stars

4.3K

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode64

gemini-cli63

codex61

claude-code60

cursor59

github-copilot57