ag-kit: Skill for Claude Code

Node.js Best Practices

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

---

⚠️ 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

Decision Tree

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (~5x req/sec of Express in Fastify's own hello-world benchmark; benchmark your own 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:

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

---

2. Runtime Considerations

Native TypeScript

Node.js 24+ (Active LTS): type-stripping ON by default
├── Run .ts files directly: node file.ts (no flag, stable since 24.12)
├── Erasable syntax only — enums, runtime namespaces, param properties error out
├── For those, use tsx (--experimental-transform-types was removed in Node 26)
└── 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