2025-11-24 - Initial Research

Overview

Researching the compatibility and practical use of Bun runtime with NestJS framework.

Key Discoveries

Compatibility Breakthrough

  • Bun v1.0.3 (September 2023) was the turning point
  • Added support for TypeScript’s emitDecoratorMetadata which is essential for NestJS
  • NestJS relies heavily on decorators for dependency injection, pipes, guards, etc.

Performance Characteristics

  • Startup: ~2x faster than Node.js (~50ms vs ~100ms)
  • Throughput: Can handle ~2.4k more requests per second
  • Latency: ~30ms faster average response time
  • Memory: Generally lower memory footprint than Node.js

Limitations Found

  1. CLI Support: NestJS @nestjs/cli doesn’t have Bun as first-class runtime

    • Ongoing GitHub issue: nestjs/nest#13881
    • Users must manually configure Bun execution

  2. Type Checking: Bun doesn’t perform TypeScript type checking at runtime

    • Must use separate tsc --noEmit or other type checkers
    • This is by design for performance

  3. Package Compatibility: Some edge cases with third-party packages

    • Core NestJS packages work well
    • Optional dependencies need to handle missing gracefully
    • Most npm packages work fine, but some may need workarounds

  4. Distribution: When building for npm distribution

    • Use bun build --packages external to keep dependencies separate
    • Allows users with Node.js to run the package
    • Alternative: standalone Bun executables

Community Solutions

Multiple starter templates have emerged:

  • bunest (dung204) - Most comprehensive, includes modern setup
  • bun-nest-starter (Netoun) - Includes Drizzle ORM integration
  • bun-nestjs (letstri) - Simple, minimal example

Performance Trade-offs vs Node.js

FactorBunNode.js
Startup Speed⚡⚡⚡⚡⚡
Runtime Latency⚡⚡⚡⚡⚡
Type Safety⚠️ Manual✅ Built-in
Ecosystem Maturity🟡 Emerging✅ Mature
CLI Tool Support🟡 Limited✅ Excellent
Production Readiness✅ Yes✅ Yes

Use Cases for Bun + NestJS

Good Fit:

  • High-performance API servers (latency-sensitive)
  • New projects without legacy dependencies
  • Performance-critical microservices
  • Projects that need fast startup (serverless functions)

Consider Node.js:

  • Large existing ecosystems with many custom packages
  • Projects requiring advanced TypeScript IDE support during runtime
  • Teams with strong Node.js expertise
  • Strict requirement for CLI tool compatibility

Next Steps to Explore

  1. Create a minimal Bun + NestJS example project
  2. Benchmark actual performance with database queries
  3. Test integration with common NestJS packages (TypeORM, Prisma, etc.)
  4. Investigate Docker containerization with Bun
  5. Document migration path from Node.js to Bun