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

nodejs-best-practices

/nodejs-best-practices

Stosuje konwencje backendu Node.js: dobór frameworka, warstwy API, propagacja błędów, wydajność async, walidacja na granicach, testy, bezpieczeństwo i bramki produkcyjne.

Licencja
MIT
Ostatnia zmiana repozytorium
27.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
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.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

Stosuje konwencje backendu Node.js: dobór frameworka, warstwy API, propagacja błędów, wydajność async, walidacja na granicach, testy, bezpieczeństwo i bramki produkcyjne.

Oryginalny opis (EN)

Node.js backend conventions — framework selection, API layering, error propagation, async performance, boundary validation, testing, security, and production gates. Use when architecting, building, reviewing, or deploying Node.js backend services. Not for browser/frontend JavaScript.

Jak działa

  1. 1. Framework
  2. 2. Runtime and modules
  3. 3. Architecture
  4. 4. Errors
  5. 5. Async and the event loop
  6. 6. Validation
  7. 7. Security
  8. 8. Testing
  9. 9. Production
  10. Decision checklist
Sekcje z nagłówków SKILL.md, w oryginale · 109 linii, 1 116 słów
Podgląd SKILL.md
---
name: nodejs-best-practices
description: 'Node.js backend conventions — framework selection, API layering, error propagation, async performance, boundary validation, testing, security, and production gates. Use when architecting, building, reviewing, or deploying Node.js backend services. Not for browser/frontend JavaScript.'
metadata:
  category: reference
---

# Node.js Best Practices

Evaluate project constraints and select explicit matches. For security-sensitive surfaces (auth, payments, user data, public traffic), load [SECURITY.md](SECURITY.md). Prior to deployment or containerization, load [PRODUCTION.md](PRODUCTION.md). Applying a section means every checklist item in it is accounted for: applied, or skipped with a stated reason.

## 1. Framework

Default: **Fastify** (high throughput, schema-first validation, native TypeScript). Select alternatives when constraints match:

| Condition                                                  | Choice                                                                          | Rationale                                                                                                    |
| :--------------------------------------------------------- | :------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------- |
| Edge/serverless, or minimal-footprint general Node service | **Hono**                                                                        | ~14KB, web-standard Request/Response; identical code on Node (`@hono/node-server`), Bun, Deno, edge runtimes |
| Enterprise codebases requiring structured DI               | **NestJS**                                                                      | Enforced modular conventions across teams (Express 5 by default; swap in the Fastify adapter for throughput) |
| Codebase with an established Express middleware ecosystem  | **Express**                                                                     | Express 5.x is stable; ecosystem compatibility                                                               |
| Type-safe full-stack RPC API                               | **tRPC** (internal TS monorepo) or **oRPC** (adds OpenAPI + REST compatibility) | Shared end-to-end TypeScript types                                                                           |

## 2. Runtime and modules

- **Runtime**: Node.js Active LTS pinned via `.nvmrc` and `package.json#engines`. Use native `node --watch` for local development hot-reloading (eliminating nodemon). (Bun/Deno reserved for dedicated standalone tooling).
- **TypeScript**: Use Node built-in type stripping (`--experimental-strip-types` since 22.6, unflagged since 23.6, stable since 24) for lightweight scripts and small services adhering to erasable syntax (interfaces, type aliases, type-only imports; enums, namespaces, and parameter properties need `--experimental-transform-types` instead of the stable stripper). Enforce with TypeScript's `erasableSyntaxOnly` compiler option (TS 5.8+) so the codebase never silently drifts onto non-erasable syntax. Use standard build tools (`tsc`, `tsup`, `tsx`, `esbuild`) for production services and decorator-heavy frameworks (NestJS).
- **Modules**: ESM (`import`/`export`) by default. Import built-ins with explicit `node:` prefix (`node:fs/promises`, `node:crypto`).

## 3. Architecture

Organize by **business domain module** (`users/`, `orders/`, `billing/`), each internally layered:

```
module/
├── routes/controller  — HTTP transport, parameter extraction, boundary validation
├── service            — business logic, framework-agnostic
└── repository         — data access, database queries, ORM entities
```

Configuration resolves hierarchically: defaults < `.env` (loaded natively via `node --env-file=.env`) < environment variables. Load secrets strictly from environment variables or a secret manager.

## 4. Errors

Split errors into two distinct lifecycles:

- **Operational errors** (invalid input, resource not found, upstream timeout): Return structured HTTP responses and maintain continuous uptime.
- **Programmer errors** (unhandled exceptions, null dereferences): Log error context, stop accepting new connections, drain active requests, and forcefully terminate (`process.exit(1)`) to let the container orchestrator restart a clean instance.

Handling rules:

- Throw custom domain error classes carrying HTTP status codes and machine-readable `code` identifiers.
- Consolidate error mapping in a single central error middleware at application root.
- Server logs receive stack trace, request parameters, and correlation ID; HTTP responses receive only user-safe message, status, and code.
- Return or `await` all promises inside async handlers to preserve full asynchronous stack traces.
- Attach error event listeners to streams, event emitters, and process unhandled rejection hooks.

## 5. Async and the event loop

- Execute independent asynchronous operations concurrently with `Promise.all` or `Promise.allSettled`.
- Offload CPU-bound tasks (cryptography, image transformations, heavy parsing) to worker threads, background queues, or dedicated services.
- Use `node:fs/promises` in request execution paths; reserve synchronous `fs` methods exclusively for startup initialization.
- Stream large file payloads and database query results rather than buffering in memory.
- Prefer modern built-in APIs over third-party packages: `node:crypto.randomUUID()`, `structuredClone()`, global `fetch`/`Request`/`Response`, `node:util.parseArgs()`, `AsyncLocalStorage` (`node:async_hooks`) for request context propagation, and `performance.eventLoopUtilization()` (`node:perf_hooks`) for event loop health.

## 6. Validation

Validate all external inputs at the boundary: request body, query params, headers, environment variables, and third-party API responses.

Default: **Zod v4** (2.3× smaller core bundle, up to 14× faster parsing, ~100× faster type instantiation than v3 — confirm the lockfile resolves v4, not legacy v3). Switch when constraints match: edge bundle size $\rightarrow$ **Valibot**, or `zod/mini` (~1.9KB) to stay on the Zod ecosystem; hot-path throughput $\rightarrow$ **ArkType** (Zod v4 has narrowed this gap significantly — benchmark before switching). Reject invalid payloads immediately at the route boundary before passing to domain services.

## 7. Security

Baseline requirements for every service (full hardening checklist: [SECURITY.md](SECURITY.md) — load for auth, payment, public-facing, or compliance-sensitive work):

- Validate all boundary inputs with strict schemas; parameterize all database queries.
- Hash passwords with `argon2id`; pin JWT algorithms and verify signature and expiration.
- Apply rate limiting on public and auth endpoints; enforce payload size caps.
- Enable security headers via `helmet`; configure explicit CORS allowed domain origins.
- Load secrets strictly from environment/secret managers; enforce committed lockfile via `npm ci --ignore-scripts`, and verify package provenance/signatures (`npm audit signatures`) for critical dependencies.
- Check regular expressions for ReDoS vulnerabilities to protect the single-threaded event loop.

## 8. Testing

Default runner: built-in `node --test` with `node:assert` — stable, with built-in mocking (`mock.fn`, `mock.module`, `mock.timers`), coverage, and watch mode. Switch to **Vitest** for snapshot testing (`node:test`'s one missing feature), richer mocking ergonomics, or Jest compatibility. API integration tests via **Supertest** or native `fetch` against the test server instance.

Execution standards:

- Structure test cases with explicit context and expected outcome; organize bodies into **Arrange–Act–Assert**.
- Provide isolated database records per test case; mock external third-party HTTP dependencies.
- For critical paths (auth, billing, transactional workflows), assert all applicable side effects: response payload, database state mutations, outbound HTTP calls, queued jobs, and emitted telemetry.

## 9. Production

Pre-deploy baseline (full production and Docker checklist: [PRODUCTION.md](PRODUCTION.md) — load before deployment, containerization, or scaling work):

- Set `NODE_ENV=production`, pin Active LTS Node, and execute `npm ci` from committed lockfile.
- Stream structured JSON logs directly to `stdout` with request correlation IDs via Pino.
- Instrument distributed tracing and metrics with OpenTelemetry (`@opentelemetry/sdk-node` + auto-instrumentations, bootstrapped via `node --import`), correlated with Pino logs through shared trace/span IDs.
- Maintain stateless processes; delegate TLS termination, compression, and static assets to a reverse proxy.
- Implement graceful shutdown on `SIGTERM` with active connection draining and hard exit timeout.

## Decision checklist

Account for each item before completing implementation; clarify ambiguous constraints with the user:

- [ ] Framework selected according to routing and runtime requirements.
- [ ] Active LTS Node version pinned in `.nvmrc` and `package.json`.
- [ ] Codebase structured into domain modules with route, service, and repository layers.
- [ ] Central error-handling middleware registered with operational vs programmer error branching.
- [ ] Asynchronous request paths free of blocking synchronous calls or unhandled promise rejections.
- [ ] Input validation schemas attached to all route handlers and environment variables.
- [ ] Integration tests verify response payload and persistent state mutations for critical flows.
- [ ] Loaded [SECURITY.md](SECURITY.md) for public, auth, or sensitive data surfaces.
- [ ] Loaded [PRODUCTION.md](PRODUCTION.md) prior to containerization and deployment.
Pliki w paczce (3)
  • PRODUCTION.md 4 KB
  • SECURITY.md 4 KB
  • SKILL.md 10 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · j0hanz/j0hanz-marketplace100MIT
Reprograme/redevkit100MIT
jeffersonvalente/cardume100MIT

Migawka bazy z 13.11.2026 · wersja paczki c2e16b6f4d2c (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

  • 100nodejs-backend
    Stosuje wzorce backendu Node.js: dobór frameworka, architektura warstwowa, TypeScript, walidacja, obsługa błędów, bezpieczeństwo i wdrożenie produkcyjne.
  • 100nodejs-backend-patterns
    Buduje produkcyjne usługi backendowe w Node.js z Express lub Fastify: wzorce middleware, obsługa błędów, uwierzytelnianie, integracja z bazą danych i dobre praktyki API.
  • 90nodejs-backend-engineering
    Pomaga projektować, przeglądać i naprawiać usługi oraz workery backendowe w Node.js, w tym zachowanie async, integracje i odzyskiwanie po awarii.
  • 100nodejs-expert
    Wspiera pracę z backendem Node.js: Express, wzorce async, strumienie, optymalizacja wydajności, operacje na systemie plików i żądania HTTP, w praktyce produkcyjnej.
  • 91nodejs-backend-patterns
    Buduje produkcyjne usługi backendowe w Node.js z Express lub Fastify: middleware, obsługa błędów, uwierzytelnianie, integracja z bazą danych i projektowanie API.
  • 100nodejs-backend-expert
    Doradza w backendach Node.js (Express, Fastify, Hono): routing, middleware, walidacja, uwierzytelnianie, async oraz utwardzanie produkcyjne i naprawa błędów asynchronicznych.

Uwagi i zgłoszenia

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