nodejs-best-practices

Q: How do I install nodejs-best-practices?

Run npx skills add https://github.com/sickn33/agentic-awesome-skills --skill nodejs-best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/nodejs-best-practices/ (personal) or .claude/skills/nodejs-best-practices/ (project).

by sickn33Backend & APIs

Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.

Installs: 13.8K
Last 24h: +18
Trending rank: #6232
Security: Pass

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/sickn33/agentic-awesome-skills --skill nodejs-best-practices

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads nodejs-best-practices automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·The skill is a collection of educational guidelines and architectural principles for Node.js development. It does not contain any executable code, network requests, or sensitive data access.

Socket PassNo alerts

Snyk PassLOW ·Risk: LOW · No issues

SKILL.md

The instructions your agent reads when the skill is triggered.

Node.js Best Practices

Principles and decision-making for Node.js development in 2025. Learn to THINK, not memorize code patterns.

When to Use

Use this skill when making Node.js architecture decisions, choosing frameworks, designing async patterns, or applying security and deployment best practices.

⚠️ How to Use This Skill

This skill teaches decision-making principles, not fixed code to copy.

ASK user for preferences when unclear
Choose framework/pattern based on CONTEXT
Don't default to same solution every time

1. Framework Selection (2025)

Decision Tree

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (benchmark the actual workload)
│
├── Enterprise/Team familiarity
│   └── NestJS (structured, DI, decorators)
│
├── Legacy/Stable/Maximum ecosystem
│   └── Express (mature, most middleware)
│
└── Full-stack with frontend
    └── Next.js API Routes or tRPC

Comparison Principles

Factor	Hono	Fastify	Express
Best for	Edge, serverless	Performance	Legacy, learning
Cold start	Fastest	Fast	Moderate
Ecosystem	Growing	Good	Largest
TypeScript	Native	Excellent	Good
Learning curve	Low	Medium	Low

Selection Questions to Ask:

What's the deployment target?
Is cold start time critical?
Does team have existing experience?
Is there legacy code to maintain?

2. Runtime Considerations (2025)

Native TypeScript

Node.js TypeScript support depends on the exact runtime version and syntax; verify the installed release before using type stripping
├── Run .ts files directly
├── No build step needed for simple projects
└── Consider for: scripts, simple APIs

Module System Decision

ESM (import/export)
├── Modern standard
├── Better tree-shaking
├── Async module loading
└── Use for: new projects

CommonJS (require)
├── Legacy compatibility
├── More npm packages support
└── Use for: existing codebases, some edge cases

Runtime Selection

Runtime	Best For
Node.js	General purpose, largest ecosystem
Bun	Performance, built-in bundler
Deno	Security-first, built-in TypeScript

3. Architecture Principles

Layered Structure Concept

Request Flow:
│
├── Controller/Route Layer
│   ├── Handles HTTP specifics
│   ├── Input validation at boundary
│   └── Calls service layer
│
├── Service Layer
│   ├── Business logic
│   ├── Framework-agnostic
│   └── Calls repository layer
│
└── Repository Layer
    ├── Data access only
    ├── Database queries
    └── ORM interactions

Why This Matters:

Testability: Mock layers independently
Flexibility: Swap database without touching business logic
Clarity: Each layer has single responsibility

When to Simplify:

Small scripts → Single file OK
Prototypes → Less structure acceptable
Always ask: "Will this grow?"

4. Error Handling Principles

Centralized Error Handling

Pattern:
├── Create custom error classes
├── Throw from any layer
├── Catch at top level (middleware)
└── Format consistent response

Error Response Philosophy

Client gets:
├── Appropriate HTTP status
├── Error code for programmatic handling
├── User-friendly message
└── NO internal details (security!)

Logs get:
├── Full stack trace
├── Request context
├── User ID (if applicable)
└── Timestamp

Status Code Selection

Situation	Status	When
Bad input	400	Client sent invalid data
No auth	401	Missing or invalid credentials
No permission	403	Valid auth, but not allowed
Not found	404	Resource doesn't exist
Conflict	409	Duplicate or state conflict
Validation	422	Schema valid but business rules fail
Server error	500	Internal failure; log redacted diagnostic context

5. Async Patterns Principles

When to Use Each

Pattern	Use When
`async/await`	Sequential async operations
`Promise.all`	Parallel independent operations
`Promise.allSettled`	Parallel where some can fail
`Promise.race`	First settled result; a timeout race does not cancel underlying work

Event Loop Awareness

I/O-bound (async helps):
├── Database queries
├── HTTP requests
├── File system
└── Network operations

CPU-bound (async doesn't help):
├── Crypto operations
├── Image processing
├── Complex calculations
└── → Use worker threads or offload

Avoiding Event Loop Blocking

Never use sync methods in production (fs.readFileSync, etc.)
Offload CPU-intensive work
Use streaming for large data

6. Validation Principles

Validate at Boundaries

Where to validate:
├── API entry point (request body/params)
├── Before database operations
├── External data (API responses, file uploads)
└── Environment variables (startup)

Validation Library Selection

Library	Best For
Zod	TypeScript first, inference
Valibot	Smaller bundle (tree-shakeable)
ArkType	Performance critical
Yup	Existing React Form usage

Validation Philosophy

Fail fast: Validate early
Be specific: Clear error messages
Don't trust: Even "internal" data

7. Security Principles

Security Checklist (Not Code)

Security Mindset

Trust nothing:
├── Query params → validate
├── Request body → validate
├── Headers → verify
├── Cookies → validate
├── File uploads → scan
└── External APIs → validate response

8. Testing Principles

Test Strategy Selection

Type	Purpose	Tools
Unit	Business logic	node:test, Vitest
Integration	API endpoints	Supertest
E2E	Full flows	Playwright

What to Test (Priorities)

Critical paths: Auth, payments, core business
Edge cases: Empty inputs, boundaries
Error handling: What happens when things fail?
Not worth testing: Framework code, trivial getters

Built-in Test Runner (Node.js 22+)

node --test src/**/*.test.ts
├── No external dependency
├── Good coverage reporting
└── Watch mode available

9. Anti-Patterns to Avoid

❌ DON'T:

Use Express for new edge projects (use Hono)
Use sync methods in production code
Put business logic in controllers
Skip input validation
Hardcode secrets
Trust external data without validation
Block event loop with CPU work

✅ DO:

Choose framework based on context
Ask user for preferences when unclear
Use layered architecture for growing projects
Validate all inputs
Use environment variables for secrets
Profile before optimizing

10. Decision Checklist

Before implementing:

Asked user about stack preference?
Chosen framework for THIS context? (not just default)
Considered deployment target?
Planned error handling strategy?
Identified validation points?
Considered security requirements?

Remember: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.

Limitations

Framework comparisons are qualitative and version/workload dependent. Examples are not benchmark evidence. Use explicit cancellation/deadlines for underlying I/O and redact secrets/PII from diagnostic context.
Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

FAQ

What does the nodejs-best-practices skill do?

Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.

How do I install nodejs-best-practices?

Run npx skills add https://github.com/sickn33/agentic-awesome-skills --skill nodejs-best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/nodejs-best-practices/ (personal) or .claude/skills/nodejs-best-practices/ (project).

Which AI agents can use nodejs-best-practices?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is nodejs-best-practices safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains nodejs-best-practices?

It is published by sickn33 in sickn33/agentic-awesome-skills. It has 13,836 recorded installs.