Claude Skill

nodejs-backend

Node.js backend patterns: layered architecture, TypeScript, validation, error handling, security, observability, logging, metrics, deployment. Use when building REST APIs, REST endpoints, middleware, Express/Fastify/Hono/NestJS/Koa servers, tRPC procedures, Bun servers, or server

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download iliaal-ai-skills-skills_nodejs-backend-6e16f4a.zip · 27 KB

Install

skills CLI npx skills add https://github.com/iliaal/ai-skills/tree/master/skills/nodejs-backend
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install iliaal-ai-skills@llmmart
Git git clone https://github.com/iliaal/ai-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole iliaal/ai-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Node.js Backend

Verify before implementing: For framework-specific APIs (Express 5, Fastify 5, Node.js 22+ built-ins), look up current, version-matched official docs before writing code. Prefer Context7 (query-docs) when available. Otherwise use available web tools to read the framework's official documentation, or the Node.js API docs for Node.js built-ins. Training data may lag current releases.

Working rules

  • Validate request and third-party data before use; keep response serialization and error envelopes explicit.
  • Preserve caller-visible contracts and authorization when adding resilience or fallbacks.
  • Bound concurrency, set timeouts, and avoid blocking production request paths.
  • Verify actual resource identity before parsing or caching a reused client's result.
  • Exercise operational telemetry and failure paths, not successful return codes alone.

Architecture

src/
├── routes/          # HTTP: parse request, call service, format response
├── middleware/       # Auth, validation, rate limiting, logging
├── services/        # Business logic (no HTTP types)
├── repositories/    # Data access only (queries, ORM)
├── config/          # Env, DB pool, constants
└── types/           # Shared TypeScript interfaces
  • Routes never contain business logic
  • Services never import Request/Response
  • Repositories never throw HTTP errors
  • Dependencies point inward only (Clean Architecture rule): routes -> services -> repositories. Never the reverse.
  • For scripts/prototypes: single file is fine; ask "will this grow?"

TypeScript Rules

  • Use import type { } for type-only imports; eliminates runtime overhead
  • Prefer interface for object shapes (2-5x faster type resolution than intersections)
  • Prefer unknown over any; forces explicit narrowing
  • Use z.infer<typeof Schema> as single source of truth; never duplicate types and schemas
  • Minimize as assertions; use type guards instead
  • Add explicit return types to exported functions (faster declaration emit)
  • Untyped package? declare module 'pkg' { const v: unknown; export default v; } in types/ambient.d.ts

Discipline

  • Simplicity first: every change as simple as possible, impact minimal code
  • Only touch what's necessary; avoid introducing unrelated changes
  • No hacky workarounds: if a fix feels wrong, step back and implement the clean solution
  • Before adding a new abstraction, verify it appears in 3+ places. If not, inline it.
  • If a fix requires bypassing TypeScript (as any, non-null assertions on untrusted data, // @ts-ignore), treat it as a design smell and find the typed solution

Verify

  • tsc --noEmit passes with zero errors
  • npm test passes with zero failures
  • No TypeScript bypasses (as any, @ts-ignore) in new code

References

Task-specific references

Read the relevant reference before implementing or reviewing the matching behavior:

  • For framework choice, input validation, API contracts, or errors: api-boundaries.md.
  • For concurrency, networking, startup, caches, lifecycle cleanup, or telemetry: async-and-production.md.
  • For span kinds, HTTP-status-to-span-status rules, sampling placement, metric cardinality, or telemetry data governance: observability-tracing.md.

Existing specialized references, when the corresponding topic applies:

Files (ai-skills)
  • references
    • api-boundaries.md 10.7 KB
      Loading…
    • api-design.md 6.1 KB
      Loading…
    • async-and-production.md 12.4 KB
      Loading…
    • database-production.md 4.2 KB
      Loading…
    • observability-tracing.md 3.7 KB
      Loading…
    • security.md 6.7 KB
      Loading…
    • typescript-config.md 3.8 KB
      Loading…
  • SKILL.md 4.3 KB
    ---
    name: nodejs-backend
    class: language
    description: >-
      Node.js backend patterns: layered architecture, TypeScript, validation, error
      handling, security, observability, logging, metrics, deployment. Use when building REST APIs, REST endpoints, middleware,
      Express/Fastify/Hono/NestJS/Koa servers, tRPC procedures, Bun servers, or server-side TypeScript.
    paths:
      - "**/*.ts"
      - "**/*.js"
      - "**/*.mjs"
      - "**/*.cjs"
    ---
    
    # Node.js Backend
    
    **Verify before implementing**: For framework-specific APIs (Express 5, Fastify 5, Node.js 22+ built-ins), look up current, version-matched official docs before writing code. Prefer Context7 (`query-docs`) when available. Otherwise use available web tools to read the framework's official documentation, or the [Node.js API docs](https://nodejs.org/api/) for Node.js built-ins. Training data may lag current releases.
    
    ## Working rules
    
    - Validate request and third-party data before use; keep response serialization and error envelopes explicit.
    - Preserve caller-visible contracts and authorization when adding resilience or fallbacks.
    - Bound concurrency, set timeouts, and avoid blocking production request paths.
    - Verify actual resource identity before parsing or caching a reused client's result.
    - Exercise operational telemetry and failure paths, not successful return codes alone.
    
    ## Architecture
    
    ```
    src/
    ├── routes/          # HTTP: parse request, call service, format response
    ├── middleware/       # Auth, validation, rate limiting, logging
    ├── services/        # Business logic (no HTTP types)
    ├── repositories/    # Data access only (queries, ORM)
    ├── config/          # Env, DB pool, constants
    └── types/           # Shared TypeScript interfaces
    ```
    
    - Routes never contain business logic
    - Services never import Request/Response
    - Repositories never throw HTTP errors
    - Dependencies point inward only (Clean Architecture rule): routes -> services -> repositories. Never the reverse.
    - For scripts/prototypes: single file is fine; ask "will this grow?"
    
    
    ## TypeScript Rules
    
    - Use `import type { }` for type-only imports; eliminates runtime overhead
    - Prefer `interface` for object shapes (2-5x faster type resolution than intersections)
    - Prefer `unknown` over `any`; forces explicit narrowing
    - Use `z.infer<typeof Schema>` as single source of truth; never duplicate types and schemas
    - Minimize `as` assertions; use type guards instead
    - Add explicit return types to exported functions (faster declaration emit)
    - Untyped package? `declare module 'pkg' { const v: unknown; export default v; }` in `types/ambient.d.ts`
    
    
    ## Discipline
    
    - Simplicity first: every change as simple as possible, impact minimal code
    - Only touch what's necessary; avoid introducing unrelated changes
    - No hacky workarounds: if a fix feels wrong, step back and implement the clean solution
    - Before adding a new abstraction, verify it appears in 3+ places. If not, inline it.
    - If a fix requires bypassing TypeScript (`as any`, non-null assertions on untrusted data, `// @ts-ignore`), treat it as a design smell and find the typed solution
    
    
    ## Verify
    
    - `tsc --noEmit` passes with zero errors
    - `npm test` passes with zero failures
    - No TypeScript bypasses (`as any`, `@ts-ignore`) in new code
    
    
    ## References
    
    - [TypeScript config](./references/typescript-config.md): tsconfig, ESM, branded types, compiler performance
    - [Security](./references/security.md): JWT, password hashing, rate limiting, OWASP
    - [API design patterns](./references/api-design.md): pagination, filtering, sorting, deprecation, idempotency-key claim and retention
    - [Database & production](./references/database-production.md): connection pooling, transactions, Docker, logging
    
    ## Task-specific references
    
    Read the relevant reference before implementing or reviewing the matching behavior:
    
    - For framework choice, input validation, API contracts, or errors: [api-boundaries.md](./references/api-boundaries.md).
    - For concurrency, networking, startup, caches, lifecycle cleanup, or telemetry: [async-and-production.md](./references/async-and-production.md).
    - For span kinds, HTTP-status-to-span-status rules, sampling placement, metric cardinality, or telemetry data governance: [observability-tracing.md](./references/observability-tracing.md).
    
    Existing specialized references, when the corresponding topic applies:
    
  • SPEC.md 4.3 KB
    Loading…

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.