Node.js Best Practices workflow skill. Use this skill when the user needs Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
Instrucciones de origen · Vista previa de solo lectura
name
nodejs-best-practices-v3
description
Node.js Best Practices workflow skill. Use this skill when the user needs Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
This skill preserves the upstream intent: teach operators how to make sound Node.js decisions instead of copying fashionable patterns.
In this curated form, the skill is optimized for analysis and review of Node.js codebases, services, workers, CLIs, and internal tooling. It is especially useful when you need to assess:
runtime and release-line fit
event-loop safety and async correctness
framework necessity versus built-in platform features
dependency and supply-chain discipline
testing, diagnostics, and observability maturity
security posture and operational readiness
This is a decision-making skill, not a code-generation template. Use it to produce a justified review, recommendation, or architecture direction.
When to Use
Use this skill when:
a team asks whether a Node.js service is production-ready
you need to review architecture, framework choice, or async patterns
a repository shows latency spikes, blocking work, or unstable concurrency behavior
you need to judge whether built-in Node features can replace unnecessary dependencies
you need a structured review of security, testing, diagnostics, or release hygiene
the user wants best practices with rationale, trade-offs, and review criteria
Do not use this skill as the primary workflow when:
the task is language-agnostic and not meaningfully Node-specific
the user only wants implementation code with no review or architecture component
the dominant problem is infrastructure-only and not connected to Node runtime behavior
the codebase is browser-only JavaScript with no Node runtime concerns
Workflow
Establish the review target
Identify whether the subject is an API server, CLI, worker, monolith, library, or mixed repository.
Record the Node version policy from .nvmrc, .node-version, package.json, CI config, Dockerfile, or deployment manifests.
Confirm whether the question is about architecture, correctness, performance, security, or release readiness.
Map runtime responsibilities
Separate I/O-bound work from CPU-bound work.
Note where the process handles HTTP, queues, cron jobs, file I/O, streams, child processes, or crypto/compression.
Flag any work that appears likely to block the event loop.
Review platform-fit decisions
Check whether the codebase uses built-in capabilities appropriately before adding dependencies.
Look for valid use of modern Node facilities such as node:test, AsyncLocalStorage, diagnostics_channel, built-in fetch, --env-file, and permissions where relevant.
Challenge framework or library choices that add abstraction without solving a concrete problem.
Assess correctness and maintainability
Review async boundaries, error propagation, cancellation, shutdown behavior, and timeouts.
Check whether configuration is explicit, validated, and environment-specific.
Verify that modules, services, and adapters are separated cleanly enough to test and replace.
Assess dependency and supply-chain discipline
Review lockfile presence, install reproducibility, dependency sprawl, and package freshness.
Prefer npm ci-style reproducible installs in CI over drift-prone install flows.
Check whether dependency risk is controlled with minimal package count, provenance-aware publishing or consumption where applicable, and actionable audit handling rather than blind upgrades.
Assess testing and diagnostics
Check whether tests cover behavior at the right level: unit, integration, contract, and failure-path tests.
Look for observability support: structured logs, request or job correlation, health signals, metrics hooks, and useful crash diagnostics.
Review whether production debugging relies on stable mechanisms instead of ad hoc console.log sprawl.
Confirm graceful shutdown, backpressure handling, and retry logic do not create duplicate work or data corruption.
Check whether defaults are safe under failure, not only under happy-path traffic.
Produce a decision-oriented output
Summarize findings as keep, change, or investigate.
Prioritize by impact: correctness and security first, then operability, then maintainability.
Recommend the smallest safe change that materially improves the system.
Review Output Format
Use this structure when presenting results:
Context: what the service does and what Node is responsible for
Strengths: practices worth preserving
Critical risks: issues that can cause outages, corruption, or security exposure
Important improvements: changes that improve resilience or clarity
Optional refinements: nice-to-have improvements with lower urgency
Decision summary: whether the current approach is acceptable, conditionally acceptable, or should be changed
Examples
Example 1: Short review summary
Target: Express-based internal API on Node 22
Decision: Conditionally acceptable
Strengths:
- Uses LTS runtime in CI and production
- Has a lockfile and reproducible CI install
- Uses structured logging and graceful shutdown hooks
Critical risks:
- Image processing runs inline on request path and blocks the event loop
- Request timeouts are missing on outbound fetch calls
- Input validation is inconsistent across routes
Important improvements:
- Move CPU-heavy image work to a worker or separate service
- Wrap outbound I/O with explicit timeout and retry policy
- Centralize schema validation at the edge
Example 2: Framework challenge
Question: Should this small JSON API keep a large framework stack?
Observed facts:
- 12 routes, minimal middleware, no SSR, no plugin ecosystem dependency
- Most code is validation, auth checks, and data access
- Team cites convenience, not a hard technical requirement
Reasoned recommendation:
- Re-evaluate framework weight versus built-in HTTP support or a lighter server layer
- Keep the current framework only if it provides proven operational value such as standardized plugins, hooks, or team-wide conventions
- Do not rewrite purely for fashion; rewrite only if complexity reduction is measurable
For deeper worked examples, open:
examples/review-example.md
examples/decision-scenarios.md
Best Practices
Do
Prefer current supported Node release lines and document the target runtime explicitly.
Distinguish CPU-bound work from I/O-bound work before discussing performance.
Use built-in platform features when they meet the requirement cleanly.
Require explicit timeouts, cancellation strategy, and error handling for outbound I/O.
Keep request handlers thin; move business rules into testable modules.
Preserve correlation context across async boundaries when tracing request or job flow matters.
Use reproducible installs and review dependency additions as architecture decisions, not convenience-only changes.
Treat observability as part of correctness: if failures cannot be diagnosed, the system is not truly production-ready.
Do Not
Recommend a framework because it is popular without tying it to delivery or operational benefit.
Assume async code is safe just because it uses await.
Put compression, crypto, large JSON transforms, image manipulation, or heavy parsing directly on hot request paths without justification.
Accept unbounded concurrency, unbounded queues, or unbounded payload handling.
Add packages for features already provided adequately by Node unless the package clearly reduces risk or complexity.
Treat npm audit output as a mechanical upgrade queue; evaluate exploitability, reachability, and breakage risk.
Rely on scattered environment variables with no validation or startup checks.
Troubleshooting
Symptoms: Latency spikes under moderate traffic, CPU rises sharply, and unrelated requests slow down.
Solution: Review for event-loop blocking work such as sync filesystem calls, large JSON parsing/stringifying, crypto/compression on the request path, regex backtracking, or CPU-heavy transforms. Move CPU-bound work to workers, queues, or another service boundary where justified.
Symptoms: The service appears "async" but still hangs or times out unpredictably.
Solution: Inspect outbound I/O for missing timeouts, retries without bounds, unresolved promises, and connection-pool exhaustion. Verify that every network call has explicit timeout behavior and failure handling.
Symptoms: Logs are present, but incidents are still hard to trace across requests or jobs.
Solution: Check whether correlation IDs or async context propagation are preserved consistently. Prefer structured logs and stable context propagation over ad hoc string logging.
Symptoms: CI passes, but production fails after dependency updates or environment changes.
Solution: Check for non-reproducible installs, weak lockfile discipline, runtime version drift, and configuration assumptions hidden in shell environments. Confirm that CI and production use the same Node major line and installation strategy.
Symptoms: Memory growth appears gradual and hard to reproduce.
Solution: Review long-lived caches, event listeners, stream lifecycle handling, and request-scoped state retained beyond completion. Check whether backpressure is ignored or whether large objects remain referenced in closures.
For a faster diagnosis matrix, open references/troubleshooting-matrix.md.
Additional Resources
references/review-criteria.md — Open this when you need a compact but concrete Node.js review checklist with decision criteria.
references/troubleshooting-matrix.md — Open this when symptoms are operational and you need likely causes plus targeted review checks.
examples/review-example.md — Open this when you need a worked example of a review with findings and prioritization.
examples/decision-scenarios.md — Open this when the user is asking "should we use X?" and you need scenario-based decisions.
Scope Notes
This skill favors judgment and review quality over style debates. The best output is usually not "rewrite everything," but "keep what is working, change the parts that create measurable risk, and justify each recommendation in Node-specific terms."
