Skip to main content

20. NestJS Application Framework

Status: Accepted Date: 2025-07-06

Context​

The Mercury backend is a complex, multi-component system (the "Pantheon") that requires a solid architectural foundation. Building it from scratch with a minimal framework like Express would lead to inconsistent design patterns, significant boilerplate for common tasks (like dependency injection and module management), and long-term maintenance challenges as the system grows. A structured, opinionated framework is needed to enforce consistency and provide essential features out of the box.

Decision​

We will use the NestJS framework as the foundation for the mercury-backend application and other backend services in the monorepo. NestJS provides an opinionated, modular architecture that is heavily inspired by Angular. Its core features, such as a powerful dependency injection system, a robust module architecture, and first-class TypeScript support, are critical for building a scalable and maintainable enterprise-grade application.

Consequences​

Positive:

  • Structured Architecture: NestJS enforces a clean, modular architecture, which is ideal for managing the many components of the Pantheon system.
  • Dependency Injection: The built-in DI container simplifies testing, promotes loose coupling, and makes managing dependencies between services trivial.
  • Developer Productivity: The framework provides solutions for common web development problems (e.g., routing, validation, configuration), allowing developers to focus on business logic. The CLI helps scaffold new components quickly.
  • TypeScript First: Its excellent TypeScript integration provides strong typing and better developer tooling from the start.

Negative:

  • Learning Curve: NestJS is highly opinionated and has a steeper learning curve compared to more minimalist frameworks like Express. Developers need to understand concepts like modules, decorators, and providers.
  • Boilerplate: While the CLI helps, the framework can sometimes feel verbose, requiring multiple files and decorators for simple endpoints.
  • Performance: The framework's abstraction layers can introduce a small amount of performance overhead compared to a bare-bones Node.js server, though this is negligible for most applications.

Mitigation:

  • Clear Documentation: Maintain clear internal documentation on our specific architectural patterns and best practices within NestJS to help onboard new developers faster.
  • Leverage CLI: Encourage the use of the nest-cli to automate the generation of modules, services, and controllers, which reduces boilerplate and ensures consistency.
  • Performance Monitoring: Implement performance monitoring and profiling as part of our standard observability stack to identify and address any potential bottlenecks early.