How to Use a Global Prefix for Routes in NestJS: Complete Implementation Guide

Use app.setGlobalPrefix('api') in your bootstrap function to prepend a common path segment to every controller route, with optional exclusions configured through the GlobalPrefixOptions interface.

Configuring a global prefix is essential for organizing REST APIs under a common base path like /api or /v1. In the nestjs/nest repository, this functionality is implemented at the framework level through the NestApplication class, ensuring consistent route construction across Express, Fastify, and other HTTP adapters.

Internal Implementation of setGlobalPrefix

The core mechanism resides in packages/core/nest-application.ts, specifically within the setGlobalPrefix method (lines 377-389). This method stores the prefix in the application configuration and processes optional exclusion patterns:

public setGlobalPrefix(prefix: string, options?: GlobalPrefixOptions): this {
  this.config.setGlobalPrefix(prefix);
  if (options) {
    const exclude = options?.exclude ? mapToExcludeRoute(options.exclude) : [];
    this.config.setGlobalPrefixOptions({ ...options, exclude });
  }
  return this;
}

The GlobalPrefixOptions interface, defined in packages/common/interfaces/global-prefix-options.interface.ts, provides the exclude array that accepts string paths or RouteInfo objects:

export interface GlobalPrefixOptions<T = string | RouteInfo> {
  exclude?: T[];
}

During request handling, the router concatenates the stored prefix with each controller's route path unless the request matches one of the excluded patterns normalized by mapToExcludeRoute.

Setting Up a Basic Global Prefix

To prepend /api to every route in your application, invoke setGlobalPrefix after creating the application instance in main.ts:

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // All controller routes become /api/<original-path>
  app.setGlobalPrefix('api');

  await app.listen(3000);
}
bootstrap();

Source: [sample/24-serve-static/src/main.ts](https://github.com/nestjs/nest/blob/master/sample/24-serve-static/src/main.ts#L5-L7)

This transforms a controller decorator like @Get('users') into the full path /api/users.

Excluding Routes from the Global Prefix

To maintain specific endpoints at the root level—such as health checks—provide the exclude option:

app.setGlobalPrefix('api', {
  // /health will stay at the root, not become /api/health
  exclude: ['/health'],
});

Source: [packages/common/interfaces/global-prefix-options.interface.ts](https://github.com/nestjs/nest/blob/master/packages/common/interfaces/global-prefix-options.interface.ts#L6-L8)

The exclusion logic compares incoming request paths against these patterns before applying the prefix concatenation, allowing public or monitoring endpoints to remain accessible without the API prefix.

Advanced Global Prefix Patterns

Dynamic Route Parameters

The global prefix supports route parameters for multi-tenant architectures:

// Prefix contains a tenant identifier – each request must include /api/:tenantId
app.setGlobalPrefix('/api/:tenantId');

Source: [integration/nest-application/global-prefix/e2e/global-prefix.spec.ts](https://github.com/nestjs/nest/blob/master/integration/nest-application/global-prefix/e2e/global-prefix.spec.ts#L123-L124)

This pattern allows the prefix itself to capture variables that propagate through the request pipeline alongside controller-level parameters.

Integration with API Versioning

Global prefixes compose seamlessly with NestJS versioning strategies:

// Prefix and versioning work together
app.setGlobalPrefix('v1/api');

Source: [integration/versioning/e2e/uri-versioning.spec.ts](https://github.com/nestjs/nest/blob/master/integration/versioning/e2e/uri-versioning.spec.ts#L364-L366)

When both features are enabled, the framework correctly constructs paths like /v1/api/resource, applying the prefix before the version segment.

Summary

• The setGlobalPrefix method in packages/core/nest-application.ts applies a base path to all controller routes at the framework level, independent of the HTTP platform.
• Use GlobalPrefixOptions with the exclude array to keep specific routes (e.g., /health) at the root level.
• Dynamic parameters such as :tenantId are fully supported within the prefix string for flexible API architectures.
• The feature integrates with NestJS versioning, combining prefix and version segments into the final route path.

Frequently Asked Questions

How do I exclude specific routes from the global prefix?

Pass an array of path strings or RouteInfo objects to the exclude property of GlobalPrefixOptions. The framework normalizes these patterns using mapToExcludeRoute and checks incoming requests against them before applying the prefix.

Can the global prefix contain route parameters?

Yes, the prefix string supports dynamic segments like /api/:tenantId. As demonstrated in integration/nest-application/global-prefix/e2e/global-prefix.spec.ts, these parameters are processed by the router alongside controller-level route definitions.

Does the global prefix affect API versioning?

The global prefix and versioning operate independently but compose together. When both are configured, the final route path combines the prefix with the version segment and controller path, as verified in integration/versioning/e2e/uri-versioning.spec.ts.

Where is the global prefix stored internally?

The prefix is stored in the application configuration object via this.config.setGlobalPrefix(prefix) inside the NestApplication class, making it accessible throughout the request lifecycle for route matching and URL generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}