Agent-Skills.md

Agent Skills: Performance Tuning

Optimize NestJS throughput with Fastify adapter, singleton scope enforcement, compression, and query projections. Use when switching to Fastify, diagnosing request-scoped bottlenecks, or profiling API overhead. (triggers: main.ts, FastifyAdapter, compression, SINGLETON, REQUEST scope)

UncategorizedID: hoangnguyen0403/agent-skills-standard/nestjs-performance

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/skills/nestjs/nestjs-performance

Skill Files

Browse the full folder contents for nestjs-performance.

Download Skill

Loading file tree…

skills/nestjs/nestjs-performance/SKILL.md

Skill Metadata

Name
nestjs-performance
Description
"Optimize NestJS throughput with Fastify adapter, singleton scope enforcement, compression, and query projections. Use when switching to Fastify, diagnosing request-scoped bottlenecks, or profiling API overhead. (triggers: main.ts, FastifyAdapter, compression, SINGLETON, REQUEST scope)"

Performance Tuning

Priority: P1 (OPERATIONAL)

High-performance patterns and optimization techniques for NestJS applications.

Workflow: Performance Audit

  1. Switch to Fastify — Replace Express with FastifyAdapter for ~2x throughput.
  2. Enable compression — Add Gzip/Brotli middleware.
  3. Audit provider scopes — Ensure no unintended REQUEST scope chains.
  4. Add query projections — Use select: [] on all repository queries.
  5. Profile overhead — Benchmark Total Duration, DB Execution, and API Overhead.

Fastify + Compression Setup

See implementation examples

  • Keep-Alive: Configure http.Agent keep-alive settings to reuse TCP connections for upstream services.

Scope & Dependency Injection

  • Default Scope: Adhere to SINGLETON scope (default).
  • Request Scope: AVOID REQUEST scope unless absolutely necessary.
    • Pro Tip: A single request-scoped service makes its entire injection chain request-scoped.
    • Solution: Use Durable Providers (durable: true) for multi-tenancy.
  • Lazy Loading: Use LazyModuleLoader for heavyweight modules (e.g., Admin panels).

Caching Strategy

  • Application Cache: Use @nestjs/cache-manager for computation results.
    • Deep Dive: See Caching & Redis for L1/L2 strategies and Invalidation patterns.
  • HTTP Cache: Set Cache-Control headers for client-side caching (CDN/Browser).
  • Distributed: In microservices, use Redis store, not memory store.

Queues & Async Processing

  • Offloading: Never block the HTTP request for long-running tasks (Emails, Reports, webhooks).
  • Tool: Use @nestjs/bull (BullMQ) or RabbitMQ (@nestjs/microservices).
    • Pattern: Producer (Controller) -> Queue -> Consumer (Processor).

Serialization

  • Warning: class-transformer is CPU expensive.
  • Optimization: For high-throughput READ endpoints, consider manual mapping or using fast-json-stringify (built-in fastify serialization) instead of interceptors.

Database Tuning

  • Projections: Always use select: [] to fetch only needed columns.
  • N+1: Prevent N+1 queries by using relations carefully or DataLoader for Graph/Field resolvers.
  • Connection Pooling: Configure pool size (e.g., pool: { min: 2, max: 10 }) in config to match DB limits.

Profiling & Scaling

  • API Overhead vs DB Execution: Use an "Execution Bucket" strategy to continuously benchmark Total Duration, DB Execution Time, and API Overhead.
    • Total Baseline: Excellent (< 50ms), Acceptable (< 200ms), Poor (> 500ms). Exception: Authentication routes (e.g. bcrypt/argon2) should take 300-500ms intentionally.
    • DB Execution Baseline: Excellent (< 5ms), Acceptable (< 30ms), Poor (> 100ms - implies missing index or N+1 problem).
    • API Overhead Baseline: Excellent (< 20ms), Poor (> 100ms - implies heavy synchronous processing or serialization blocking Node's event loop).
  • Offloading: Move CPU-heavy tasks (Image processing, Crypto) to worker_threads.
  • Clustering: For non-containerized environments, use ClusterModule to utilize all CPU cores. In K8s, prefer ReplicaSets.

Anti-Patterns

  • No REQUEST scope without evaluation: One REQUEST-scoped provider makes the entire chain request-scoped.
  • No CPU tasks in HTTP handler: Offload image/crypto work to worker_threads or BullMQ.
  • No unprojected queries: Always select: [] the needed columns to avoid serializing unused data.