---
name: js-typescript
description: >-
  Use this skill when writing, building, linting, testing, or releasing JavaScript or
  TypeScript — including Node, Bun, Deno, React, Next.js, and Astro projects. Covers the
  TypeScript-over-JSDoc-over-JS preference, strict compiler settings, banned constructs,
  React/hooks rules, resource lifecycle, and package/tooling choices.
---

# TypeScript / JavaScript — Rules & Preferences

Extends [`coding-dev.md`](skills-public/coding-dev.md). Everything there applies; this adds JS/TS specifics.

---

## 1. Language Choice — A Strict Preference Order

1. **TypeScript** — always the default for new code.
2. **JavaScript with JSDoc type annotations** — acceptable when a project genuinely cannot
   adopt a build step, and `checkJs` is enabled so the annotations are actually enforced.
3. **Plain untyped JavaScript** — last resort only.

Migrating an existing JS project to TS is worth proposing; do not do it unasked (scope rule).
In a plain-JS codebase, **match it** — do not introduce a lone `.ts` file and a build step
into a project that has neither.

---

## 2. Strict Compiler Settings

```jsonc
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "isolatedModules": true
  }
}
```

**`tsc --noEmit` must pass with zero errors *and* zero warnings**, and it belongs in the build
gate alongside lint and tests — not as a thing someone runs occasionally in their editor.

> [!NOTE]
> Some established codebases deliberately relax `noImplicitAny` or `noUncheckedIndexedAccess`
> because their idioms depend on it. When **contributing upstream**, respect the project's
> `tsconfig.json` as-is. In **our own repos and non-upstreamed forks**, the settings above are
> the target — tightening them is fair game (as its own change, not smuggled into a feature).

---

## 3. Banned Constructs

| Never | Use instead |
| :--- | :--- |
| `any` | `unknown` + narrowing, or a real generic |
| `as unknown as T` | a type guard, or fix the source type |
| `@ts-ignore` | `@ts-expect-error` with a one-line reason, only when unavoidable |
| `!` non-null assertion | narrow with `if` or an early return |
| `enum` / `const enum` | `as const` object + literal union |
| `namespace` | ES modules |
| Boxed primitives (`Number`, `String`, `Object`, `{}`, `Function`) | the primitive types |
| `../../..` relative climbs | the configured path alias (`@/*`) |
| `JSON.parse(JSON.stringify(x))` | `structuredClone` or `lodash.cloneDeep` |
| `await new Promise(r => setTimeout(r, ms))` | a `sleep` helper from your utils |
| `console.log` in shipped code | a real logger with levels |
| Empty `catch {}` | handle it, or let it propagate |

- **`satisfies T` over `as T`** when the value already conforms. `as` is for genuine narrowing
  only — it is an assertion that silences the checker, not a conversion.
- **Zero `any` in shared model types.** Frontend types that mirror a backend schema must stay
  structurally in sync with it and fully typed.

---

## 4. Use What Exists

**Search the codebase's own `utils/`, `common/`, and shared modules before writing anything.**
Re-implementing an export that already exists is the single most common avoidable diff.

Never hand-roll: debounce/throttle (`lodash`), deep clone, clamp, date formatting
(`date-fns` / `dayjs` / project standard), URL parsing, regex escaping, UUID generation,
retry/backoff, or a semver comparator.

In a UI framework or client mod, **never recreate a component the host already provides** —
a hand-rolled `<button>` loses theming, focus rings, and accessibility.

---

## 5. React

- **Conditional rendering returns `null`**, never `undefined` or `false`.
- **List keys are stable identifiers.** Never `key={index}` on a mutable list.
- **Don't mirror external state into `useState`.** Subscribe to the store with its own hook.
- No `useMemo` / `useCallback` on cheap values that do not feed a dependency array. They are
  not free, and they obscure what is actually expensive.
- **Hoist constant dependency arrays** to module scope (`const KEYS = [...] as const`). A fresh
  array literal in the render body re-subscribes on every render.
- Prefer `<>…</>` fragments; `React.Fragment` only when the fragment needs a `key`.
- Type props with a named `interface`, not `React.FC`.
- Wrap anything injected into a host application's tree in an error boundary — an
  uncaught throw in injected code takes down the host's render, not just yours.
- Components used as dynamic render targets must live at **module scope**. Defining a
  component inside another component remounts its whole subtree every render.

---

## 6. Resource Lifecycle — Everything Started Must Be Stopped

Every `setInterval`, long `setTimeout`, `addEventListener`, subscription, `ResizeObserver`,
`IntersectionObserver`, `AbortController`, and `WebSocket` created in a setup path must be
torn down in the matching teardown path — `stop()`, `useEffect` cleanup, or `finally`.

> [!CAUTION]
> **`addEventListener` needs a named function reference.** An inline arrow passed to
> `addEventListener` cannot be matched by `removeEventListener`, so the listener leaks
> silently and accumulates across every mount.

```ts
let intervalId: ReturnType<typeof setInterval> | undefined;

function start() { intervalId = setInterval(tick, 30_000); }
function stop()  { if (intervalId !== undefined) { clearInterval(intervalId); intervalId = undefined; } }
```

Attach an `AbortController` to every long-lived `fetch` and abort it in cleanup.

---

## 7. Structure & Naming

- **Components**: PascalCase `.tsx`.
- **Modules / utilities**: kebab-case `.ts`.
- **Imports**: prefer the configured alias (`@/…`) over relative climbs.
- Indentation and quote/semicolon style: **match the file you are editing**. Do not introduce
  a new formatter or lint config into a project that already has one.
- **One file until it earns a split** — when it nears the 1000-line limit, or when a second
  file is genuinely reusable (`utils.ts`, `types.ts`, `components/`).
  The limits from the general rules (1000 lines per file, 200 per function) apply: ESLint's `max-lines` and
  `max-lines-per-function` cover both natively, so prefer those over a separate test here.

---

## 8. Async & Data

- `async`/`await` over raw `.then()` chains. No mixing both in one flow.
- **Never leave a promise unawaited** unless you explicitly mean to, and mark it (`void p`)
  when you do.
- `Promise.all` for independent work; sequential `await` only when there is a real dependency.
- **Subscribe to events; never poll.** (Global rule — it applies with full force here.)
- **Never store secrets in `localStorage` / `sessionStorage`.** Use the platform's real
  storage API, and namespace your keys.

---

## 9. Node / Runtime Boundaries

- In any sandboxed or privileged-split architecture (Electron, browser extensions, plugin
  hosts), the untrusted side must **never** import `fs`, `path`, `child_process`, `net`,
  `http`, or `electron` directly. Route through the designated IPC/native boundary.
- Every IPC handler argument is **untrusted** — validate type, length, and content.
- Filesystem paths from the other side: `normalize()` then assert `startsWith(<allowed root>)`
  before any read or write.
- Subprocesses: `spawn` with an argv **array**. Never `exec` a constructed string, never
  `shell: true` with untrusted input.
- Network: allowlist by origin, cap response size, cap redirect depth.
- Errors crossing the boundary must be scrubbed — a raw `Error` leaks absolute paths.

---

## 10. Tooling & Tests

- Respect the project's runtime and package manager (`npm` / `pnpm` / `yarn` / `bun`) and its
  lockfile. Do not switch package managers or add a second lockfile. Build and release scripts
  around it follow [`bash.md`](skills-public/code-languages/bash.md).
- Test runner: whatever the project uses (`vitest`, `bun test`, `jest`). Tests live beside the
  code as `*.test.ts(x)` unless the project says otherwise.
- **Add unit tests for new logic and route tests for new handlers.** Prioritize coverage on
  auth, persistence, and anything that talks to a third party.
- Lint with the project's config (`eslint.config.mjs` and friends). **Do not add a new lint or
  format config** to a repo that already has one.
- **Know the project's expected test baseline.** Some inherited suites are not all-green on a
  clean checkout; judge regressions against the documented baseline rather than a raw run —
  and if a baseline file exists, use it.

---

## 11. Framework Versions Move Fast

> [!WARNING]
> Next.js, Astro, React, and the major bundlers ship breaking changes regularly, and their
> current APIs frequently differ from what is in a model's training data. **Read the version's
> own docs in `node_modules/<pkg>/dist/docs/` or the project's pinned documentation before
> writing code against them.** Heed deprecation notices rather than pattern-matching from memory.