Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

typescript-node-conventions

/typescript-node-conventions

Ustala konwencje TypeScript dla kodu na Node.js lub Bun: typowanie, granicę ESM i CJS, obsługę błędów i asynchroniczność.

Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Ustala konwencje TypeScript dla kodu na Node.js lub Bun: typowanie, granicę ESM i CJS, obsługę błędów i asynchroniczność.

Oryginalny opis (EN)

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 maps), error-handling taxonomy (typed error classes, operational vs programmer errors), async hygiene (no floating promises, flat async/await), and keeping Bun and Node interchangeable by isolating runtime-specific APIs behind a thin adapter. Trigger phrases: strict typing, unknown over any, no implicit any, ESM/CJS interop

Jak działa

  1. When to Use
  2. The Rule That Matters Most
  3. Strict Typing Discipline
  4. ESM/CJS Module Boundary
  5. Error Handling: Operational vs Programmer Errors
  6. Async Hygiene
  7. Package Exports Maps
  8. Bun/Node Interchangeability
  9. Forbidden Patterns
  10. Final Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 211 linii, 1 564 słów
Podgląd SKILL.md
---
name: typescript-node-conventions
version: "1.0.0"
description: >
  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 maps), error-handling taxonomy
  (typed error classes, operational vs programmer errors), async hygiene (no
  floating promises, flat async/await), and keeping Bun and Node
  interchangeable by isolating runtime-specific APIs behind a thin adapter.
  Trigger phrases: strict typing, unknown over any, no implicit any, ESM/CJS
  interop, moduleResolution, verbatimModuleSyntax, operational vs programmer
  errors, floating promises, unhandled rejection, exports map, dual package
  hazard, Bun Node interchangeable, runtime adapter.
license: CC-BY-4.0 AND MIT (NOTICE.md)
---

# TypeScript / Node / Bun Conventions

Condensed, actionable TypeScript-on-Node/Bun conventions distilled from the
official TypeScript Handbook and Node.js documentation. Full-depth material
lives under `references/`; this file carries everything needed to write or
review TypeScript/Node/Bun code without reading further.

> **Attribution**: The rules below adapt and paraphrase guidance from the
> official TypeScript Handbook (microsoft/TypeScript-Website, CC-BY 4.0 for
> prose) and the official Node.js documentation (nodejs/nodejs.org, MIT).
> Nothing here is reproduced verbatim — conventions are restated in original
> wording as agent-facing rules. Cross-checked against current TypeScript and
> Node.js documentation via Context7. See `NOTICE.md` for full attribution
> and license text.

## When to Use

- Writing new TypeScript for a Node.js or Bun service, CLI, or library.
- Reviewing a PR that touches `tsconfig.json`, module boundaries,
  `package.json` `exports`, error handling, or async code.
- Deciding whether code should be portable between Bun and Node, and where to
  draw the adapter line if it isn't.
- Any story whose `implementation.approach` must justify a typing, module, or
  error-handling decision on a TS/Node/Bun stack.

## The Rule That Matters Most

**`strict: true` is the non-negotiable baseline.** It is TypeScript's single
highest-leverage setting — `tsc --init` has generated it by default since
TypeScript 2.3, and TypeScript 5.9's default `tsc --init` output layers
additional stricter options (`noUncheckedIndexedAccess`,
`exactOptionalPropertyTypes`) on top of it as the current recommended
starting point. Disabling `strict` (or leaving it off in a migrated project)
forfeits most of what makes TypeScript worth using. Every rule below assumes
it is on.

## Strict Typing Discipline

- Enable `strict: true`; do not selectively disable its sub-flags
  (`strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, ...) to make a
  migration easier — fix the underlying types instead.
- **Never use `any` to silence the compiler.** For genuinely dynamic data
  (API responses, `JSON.parse` results, third-party payloads), type it
  `unknown` and narrow with `typeof`, `instanceof`, a user-defined type
  predicate, or a runtime schema check before use. `unknown` accepts any
  value but permits no operations until narrowed — that gap is the safety
  `any` throws away.
- Catch-clause variables are `unknown` under `strict` (`useUnknownInCatchVariables`,
  on since TS 4.4) — narrow with `if (err instanceof Error)` before reading
  `.message`/`.stack`; don't reflexively re-type a caught value as `any`.
- Prefer `interface` for object shapes callers might extend or implement;
  prefer `type` for unions, intersections, and mapped/conditional types. Not
  a compiler rule, but the near-universal community and linter default
  (`@typescript-eslint/consistent-type-definitions`) — pick one rationale and
  apply it consistently rather than mixing arbitrarily.
- Validate all external input (HTTP bodies, env vars, config files, queue
  messages) at the boundary with a runtime schema validator (zod/valibot or
  equivalent), not just a compile-time type. An `as SomeType` cast on
  unchecked external data is a false sense of safety — types vanish at
  runtime; only a runtime check catches a shape mismatch.

## ESM/CJS Module Boundary

- **ESM (`import`/`export`) is the default for new code.** Reach for
  CommonJS interop deliberately, not as an ad hoc per-file habit — mixing
  `require()` and `import` in the same module graph without a chosen
  boundary produces `__dirname`/`import.meta.url` confusion and dual-package
  hazards.
- Pair `"module": "nodenext"` with `"moduleResolution": "nodenext"` (implied)
  and `"verbatimModuleSyntax": true` when targeting Node — this elides
  type-only imports correctly and keeps the ESM/CJS boundary unambiguous
  instead of TypeScript silently rewriting import syntax. For bundler-driven
  targets, pair `"module": "preserve"` with `"moduleResolution": "bundler"`
  instead (implies `esModuleInterop`), which models how bundlers and
  Bun-style runtimes actually resolve modules. For a **library** meant to run
  unbundled on Node, prefer `node16`/`nodenext` resolution over `bundler` —
  `bundler` resolution can produce output that works under a bundler but
  fails under plain Node due to missing extensions.
- Modern Node (22.12+/23+) can `require()` a synchronous ESM graph directly
  — `process.features.require_module` reports whether it's active. This
  narrows, but does not eliminate, the case for ad hoc interop: still choose
  the boundary deliberately (native `require(esm)` vs. `createRequire` vs.
  dynamic `import()`) and document it, since older supported Node/Bun
  versions may not have it.
- See `references/module-boundaries.md` for the full moduleResolution
  decision table, the `exports`-map deep dive, and worked interop examples.

## Error Handling: Operational vs Programmer Errors

- **Model errors as typed classes extending `Error`**, never throw
  strings or plain objects (`throw "failed"`, `throw { code: 500 }`) — doing
  so breaks stack traces and downstream `instanceof Error` checks. Add
  discriminating fields (`code`, `isOperational`) so a `catch` can branch
  reliably.
- **Distinguish operational errors from programmer errors.** Operational
  errors are expected failures external to a bug — bad input, a timed-out
  network call, a rejected validation. Handle them locally (`try`/`catch`,
  `.catch`) and return/report a meaningful result. Programmer errors are
  bugs — a null dereference, a failed invariant, corrupted in-memory state.
  Let them crash the process and restart via a supervisor (container
  orchestrator, systemd, process manager) rather than catching and
  continuing in a state you no longer understand.
- Never swallow an error silently — an empty `catch {}`, or a `catch` that
  only logs without rethrowing or otherwise surfacing the failure, hides
  operational failures from callers and monitoring.
- Treat `unhandledRejection`/`uncaughtException` process handlers as a
  last-resort safety net for logging/telemetry before exit, never as the
  primary way an operational error gets handled.

## Async Hygiene

- **Never leave a Promise floating.** Every async call is either `await`ed
  inside a `try`/`catch`, chained with `.catch()`, or explicitly discarded
  with a `void` and a one-line comment explaining why it's fire-and-forget.
  An unhandled rejection is, by default, a process-crashing event on modern
  Node — don't rely on that default as your error-handling strategy.
- Keep control flow flat: prefer `async`/`await` over chained `.then()`, and
  don't mix callback-style APIs with promise-style APIs inside the same
  function — pick one, wrap the other at the boundary.
- See `references/async-hygiene.md` for floating-promise patterns, the
  fire-and-forget escape hatch worked example, and the full operational-vs-
  programmer error taxonomy with examples.

## Package Exports Maps

- Define a package's public surface with an explicit `exports` map in
  `package.json` rather than letting consumers deep-import into internal
  files (`pkg/dist/internal/helper.js`). `exports` is what makes internal
  refactors safe and what makes ESM/CJS dual-publishing possible at all —
  anything not listed simply isn't importable.
- When a package must serve both `require()` and `import` consumers during a
  transition, use conditional exports (`"import"`, `"require"`, and — for
  packages opting into modern Node's synchronous ESM `require`
  — `"module-sync"`) pointing at the same or equivalent ESM output, rather
  than hand-maintaining two divergent builds. Drop the transitional
  conditions once you no longer need to support Node versions that lack
  `require(esm)`.
- A dual-published package that resolves to *different module instances*
  for its CJS and ESM consumers (the "dual package hazard" — e.g. two
  separate copies of module-level state) is a bug to design out via the
  exports map, not a quirk to work around downstream.

## Bun/Node Interchangeability

- Treat Bun and Node as interchangeable for standard JS/TS logic — Bun
  targets Node API compatibility and runs Node's own test suite pre-release,
  so "write to the common surface" is a stable long-term stance.
- **Isolate runtime-specific APIs behind a thin adapter** — `Bun.serve`,
  `bun:sqlite`, `Bun.file`, or Node's `worker_threads`/`node:sqlite` go
  behind a small module boundary (e.g. `runtime/server.ts`,
  `runtime/db.ts`) with one implementation per runtime, selected at the
  composition root. Core business logic imports the adapter's interface,
  never the runtime-specific module directly.
- Don't sprinkle `typeof Bun !== "undefined"` runtime checks through
  business logic — that's the adapter boundary leaking. Push the branch to
  the edge, once, at the adapter.

## Forbidden Patterns

1. Silencing type errors with `any`, `@ts-ignore`, or `as unknown as X`
   instead of fixing the underlying mismatch or narrowing properly.
2. Throwing non-`Error` values (`throw "failed"`, `throw { code }`).
3. Swallowing errors silently — empty `catch {}`, or catch-and-log without
   rethrowing/handling.
4. Mixing `require()` and `import` ad hoc within the same module graph with
   no deliberate interop boundary.
5. Treating a programmer error (null dereference, failed assertion,
   corrupted state) as recoverable — catching it and continuing instead of
   crashing/restarting.
6. Leaving a Promise unawaited, uncaught, and undocumented ("floating").
7. Deep-importing a package's internal files instead of its declared
   `exports` map entry points.
8. Calling a runtime-specific API (`Bun.serve`, `bun:sqlite`,
   `worker_threads`) directly from shared business logic instead of through
   an adapter.

## Final Checklist

Before accepting TypeScript/Node/Bun code as convention-compliant, confirm:

- `strict: true` is on and no sub-flag is selectively disabled.
- Dynamic/external data is `unknown` + narrowed or schema-validated at the
  boundary, never cast with `any` or a bare `as`.
- `moduleResolution`/`module` match the actual runtime target, and
  `verbatimModuleSyntax` is set when targeting `nodenext`.
- Errors are typed `Error` subclasses; operational failures are handled
  locally, programmer errors are allowed to crash and restart.
- Every Promise is awaited, `.catch()`-ed, or deliberately voided with a
  documented reason — none are left floating.
- The package's public surface is declared through `exports` in
  `package.json`, not implied by file layout.
- Runtime-specific Bun/Node APIs are isolated behind a named adapter module,
  not scattered through business logic.

## Deep Reference

For full-depth material behind these condensed rules — moduleResolution
decision tables, exports-map worked examples, dual-package-hazard detail,
floating-promise patterns, and the Bun/Node adapter pattern in full — read on
demand (not auto-loaded):

- `references/module-boundaries.md` — ESM/CJS interop boundary, the full
  `moduleResolution`/`module` decision table, `package.json` `exports` map
  patterns (including `module-sync` and dual-package-hazard avoidance), and
  worked CJS/ESM interop examples.
- `references/async-hygiene.md` — floating-promise patterns and fixes, the
  fire-and-forget escape hatch worked example, the full operational-vs-
  programmer error taxonomy with code examples, and the Bun/Node adapter
  pattern worked end-to-end.
Pliki w paczce (4)
  • NOTICE.md 5 KB
  • SKILL.md 12 KB
  • references/async-hygiene.md 8 KB
  • references/module-boundaries.md 8 KB

Wersje

W bazie nie ma innych skilli o nazwie typescript-node-conventions.

Migawka bazy z 13.11.2026 · wersja paczki 9a36c04eaac4 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90conventions-typescript
    Podpowiada domyślne zasady TypeScriptu i Node.js: ścisła konfiguracja, walidacja na granicach, obsługa błędów i ESM.
  • 90neo-typescript
    Pomaga pisać, recenzować, debugować i projektować kod TypeScript: tsconfig, tryb strict, generyki, typy warunkowe i mapowane, współpraca ESM i CJS, dekoratory oraz typowanie bibliotek.
  • 100node
    Prowadzi po środowisku Node.js w projektach TypeScript: async/await i Promises, strumienie, wybór ESM lub CommonJS, exports w package.json, wybór npm, pnpm lub bun, mise i CI/CD.
  • 100typescript-expert
    Doradza w decyzjach projektowych TypeScript: project references, wydajność tsc, interop ESM i CJS oraz pliki .d.ts.
  • 90typescript-guide
    Podpowiada przy edycji i przeglądzie TypeScript w projektach Node.js ESM: funkcje async, wnioskowanie typów, tryb strict, importy ESM i zmienne środowiskowe.
  • 91node
    Wspiera tworzenie aplikacji w Node.js: pętla zdarzeń, moduły CommonJS i ESM, moduły podstawowe, wzorce asynchroniczne, diagnostyka, obsługa błędów i integracja z TypeScript.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.