typescript-conventions
/typescript-conventions
Use when a ticket adds or changes TypeScript/JavaScript code and it must follow the repo's TS conventions — strict mode typing, typescript-eslint type-aware rules, async correctness (no floating promises, bounded fan-out), boundary validation instead of casts, module/import hygiene, Node resource and concurrency safety, and idiomatic patterns. Invoke for "add this in TypeScript", "fix the type errors", "tighten the types on X", or as the language pack for any TS/JS change or TS/JS review.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when a ticket adds or changes TypeScript/JavaScript code and it must follow the repo's TS conventions — strict mode typing, typescript-eslint type-aware rules, async correctness (no floating promises, bounded fan-out), boundary validation instead of casts, module/import hygiene, Node resource and concurrency safety, and idiomatic patterns. Invoke for "add this in TypeScript", "fix the type errors", "tighten the types on X", or as the language pack for any TS/JS change or TS/JS review.
Triggers from the description
Original author description
Use when a ticket adds or changes TypeScript/JavaScript code and it must follow the repo's TS conventions — strict mode typing, typescript-eslint type-aware rules, async correctness (no floating promises, bounded fan-out), boundary validation instead of casts, module/import hygiene, Node resource and concurrency safety, and idiomatic patterns. Invoke for "add this in TypeScript", "fix the type errors", "tighten the types on X", or as the language pack for any TS/JS change or TS/JS review.
How it works
- Procedure
- Commands
- Idioms that matter
- Concurrency and resource safety
- Review checklist — flag as defects
- Capture lore
SKILL.md preview
---
name: typescript-conventions
description: Use when a ticket adds or changes TypeScript/JavaScript code and it must follow the repo's TS conventions — strict mode typing, typescript-eslint type-aware rules, async correctness (no floating promises, bounded fan-out), boundary validation instead of casts, module/import hygiene, Node resource and concurrency safety, and idiomatic patterns. Invoke for "add this in TypeScript", "fix the type errors", "tighten the types on X", or as the language pack for any TS/JS change or TS/JS review.
stack: [typescript, javascript, node, react, next, nextjs, vue, svelte, angular, react-native, expo]
area: language
---
# Write idiomatic, strict TypeScript
TypeScript protects you only as far as its types are honest: strict mode on, external
data validated rather than cast, and every promise awaited or handled. For the builder and the reviewer of a TS/JS diff; the repo's config and existing code win over it. UI framework patterns live in their own packs (the `react-patterns`
skill, the frontend packs).
## Procedure
1. **Discover the repo's conventions first.** Call `search_lore` for TS conventions. Read
`tsconfig*.json` (`strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
`module`/`moduleResolution`, `verbatimModuleSyntax`, `erasableSyntaxOnly`), the
TypeScript version (6.0 turned `strict` on by default and deprecated `baseUrl`,
`moduleResolution: node`; 7.0 removed them and ships the native `tsc`),
`package.json` (`type`, `scripts`, `engines`, `packageManager`), the lockfile that names
the package manager (`package-lock.json` npm, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`),
`eslint.config.*` or `biome.json`, Prettier config, the test runner config, and
workspace tooling (`turbo.json`, `nx.json`). Copy a sibling module and its test.
2. **Pin the exact commands** from `package.json` scripts and CI (the `run-tests` and
`run-lint` skills). Use the defaults below only when the repo defines none.
3. **Write the change with the idioms below**, then walk the concurrency section for every
promise, shared object, stream, timer, file and outbound call you touched.
4. **Test each acceptance criterion's own behaviour.** One test per AC that fails without
your change, plus its error path. If the AC involves shared state or persistence, add a
test that fires N concurrent requests (`Promise.all` over the real handler) and asserts
the invariant — Node interleaves at every `await`, so single-threaded code still races.
5. **Verify, then stop.** Done when: the type check, lint and format check are clean with
no new suppressions, tests (with the repo's coverage gate) are green, and every AC has
a test. Record the output with the `record-evidence` skill; the runner submits the work.
## Commands
- Never install: `node_modules` in a delivery worktree is shared with the main checkout,
and `npm ci`/`pnpm install`/`yarn install` are hook-blocked (the `dependency-upgrade`
skill). Run the tools already installed. Headless, plain `npx x` downloads a missing
package without asking (a missing `tsc` fetches an unrelated npm package), so always
write `npx --no -- x`, which fails instead of fetching (keep the `--`: `npx --no x`
misreads the tool name).
- Types: `npx --no -- tsc --noEmit -p .` (or `npx --no -- tsc -b` for project
references, or the repo's `typecheck` script).
- Lint and format: the repo's `lint` script (ESLint with typescript-eslint, or
`npx --no -- biome check`) and `npx --no -- prettier --check .`.
- Tests: the repo's `test` script (Vitest, Jest, `node --test`); one file:
`npx --no -- vitest run path/x.test.ts` or `npx --no -- jest path/x.test.ts`.
## Idioms that matter
- **Strict stays strict**: never loosen `tsconfig` or ESLint to pass, never add
`ignoreDeprecations`. `@ts-expect-error` with a reason beats `@ts-ignore`; both need one.
- **`unknown` over `any`** at every boundary; `catch (e)` is `unknown` — narrow it.
- **Validate, don't cast**: `await res.json() as User` and `JSON.parse(x) as T` are lies
the compiler believes. Parse with the repo's schema library (Zod, Valibot, TypeBox) and
derive the type from the schema.
- **Model precisely**: discriminated unions with an exhaustive `switch` (a `never` check
in `default`); `satisfies` over `as`; no non-null `!` on values that can be absent;
`readonly` and `as const` for data that must not change.
- **Modules**: named exports; `import type` for type-only imports (required under
`verbatimModuleSyntax`); the repo's ESM/CJS style and path aliases; `const` over `let`,
never `var`.
- **typescript-eslint** type-aware rules worth honouring even when not configured:
`no-floating-promises`, `no-misused-promises`, `await-thenable`,
`switch-exhaustiveness-check`, `no-unsafe-*`, `only-throw-error`.
- **Pitfalls**: `===` only; `arr.sort()` mutates and sorts numbers as strings (use
`toSorted((a, b) => a - b)`); `for…in` iterates keys, not elements; money is not a float.
## Concurrency and resource safety
- **Every promise is awaited, returned, or explicitly handled** (`void p.catch(log)`).
`array.forEach(async …)` does not wait; use `for…of` with `await` or `Promise.all`.
- **Bound fan-out**: `Promise.all` over user-sized input needs a concurrency limit
(the repo's limiter, e.g. `p-limit`, or a worker queue); use `Promise.allSettled` when one failure must not drop
the others' results.
- **Read-modify-write across `await`** races between concurrent requests (read, await,
write). Serialise per key (a promise-chain mutex or queue), or do it in one database
transaction or atomic update with a version check.
- **Files other requests read**: `fs.writeFile` is not atomic. Write to a unique temp path
in the same directory (`${target}.${crypto.randomUUID()}.tmp`), then `fs.rename` over the
target. Never a fixed temp name or one built from `Date.now()`. Cross-process exclusion
uses the database or a real lock; a time-only lease lets a paused holder write late, so
writes must check a fencing token or version.
- **`fetch`** resolves on 4xx/5xx — check `res.ok`; it has no default timeout — pass
`signal: AbortSignal.timeout(ms)`. Propagate `AbortSignal` through long operations.
- **Streams** use `pipeline` from `node:stream/promises` so errors and cleanup propagate;
file handles opened with `fs.promises.open` are closed in `finally`.
- **Timers and listeners** are cleared/removed when their owner ends; module-level
mutable state in a server is shared by every request.
## Review checklist — flag as defects
Walk this against the diff. An item is grounds for CHANGES only when, in changed code, it
causes a concrete failure (wrong result, crash, lost or corrupted data, security hole) or
leaves an AC's own behaviour untested: cite the line and that failure. Otherwise it is an
`(optional)` note. Formatting the tools would fix, and preferences the repo
does not enforce, are not findings. Do not patch the code under review.
- [ ] `tsconfig`/ESLint loosened; a new `any`, `@ts-ignore`, `eslint-disable` or `!`
without a reason.
- [ ] External data (request body, `JSON.parse`, `res.json()`, env) cast with `as` instead
of validated.
- [ ] A floating promise; `forEach(async …)`; an async callback passed where a sync one is
expected; an empty `catch`.
- [ ] Unbounded `Promise.all` over user-controlled input.
- [ ] A read-modify-write spanning an `await` with no per-key serialisation, transaction
or version check; shared module-level state mutated per request.
- [ ] A shared file written in place or via a fixed or time-based temp name; a time-only
lock lease.
- [ ] `fetch` without an `ok` check or a timeout; a stream piped without error handling; a
timer, listener or handle never released.
- [ ] A `switch` over a union without exhaustiveness where a new member would be missed.
- [ ] An AC has no test, or the test mocks the module the AC is about.
## Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
**A TypeScript/stack convention this repo enforces beyond the obvious — an import-ordering rule, a type-modelling pattern, or a lint/tsconfig constraint.** That kind of fact is *lore*. Capture it via the **lore-capture
protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):
call the Memory MCP `suggest_lore` once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · tmj-90/gaffer | 90 | Apache-2.0 |
| atc-net/atc-agentic-toolkit | 95 | MIT |
| baibesh/devkit-skills | 90 | MIT |
Database snapshot: 13.11.2026 · package version 1d1230dc0da9 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100typescript-eslint
typescript-eslint - ESLint plugin for TypeScript USE WHEN: user mentions "typescript-eslint", "TypeScript linting", "type-aware rules", asks about "no-floating-promises", "TypeScript ESLint config", "@typescript-eslint rules" DO NOT USE FOR: ESLint 9 full setup - use… - 100typescript
TypeScript language. Covers types, generics, and advanced patterns. Use when writing type-safe JavaScript code. USE WHEN: user mentions "typescript", "types", "generics", asks about "type safety", "type errors", "tsconfig", "utility types", "type guards", "branded types" DO NOT… - 100eslint
Expert ESLint assistance covering Flat Config (eslint.config.js), typescript-eslint, custom rules, and automated formatting. Use when enforcing code quality and preventing bugs in JavaScript/TypeScript. - 100typescript-node-conventions
Use when writing, reviewing, or setting conventions for TypeScript code that runs on Node.js or Bun — strict typing discipline (strict mode, unknown over any, no implicit any), the ESM/CJS module interop boundary (moduleResolution, verbatimModuleSyntax, package.json exports… - 100write-typescript
TypeScript coding conventions for this codebase. Use when writing or modifying TypeScript or TSX files, when TypeScript type errors appear, or when asked about strict mode, type imports, naming conventions, return types, the no-any rule, async functions, floating promises,… - 84strengthen-types
Audit and harden TypeScript type safety by finding and fixing weak typing patterns. Always use this skill whenever the user says "strengthen types", "improve TypeScript types", "fix any types", "type safety audit", "remove any from the codebase", "tighten TypeScript", "find…