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

> Learn to set a global prefix for NestJS routes using app.setGlobalPrefix() in your bootstrap function. This guide explains prepend common path segments for all controllers with optional exclusions.

- Repository: [nestjs/nest](https://github.com/nestjs/nest)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/nestjs/nest/blob/main/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:

```typescript
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`](https://github.com/nestjs/nest/blob/main/packages/common/interfaces/global-prefix-options.interface.ts), provides the `exclude` array that accepts `string` paths or `RouteInfo` objects:

```typescript
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`](https://github.com/nestjs/nest/blob/main/main.ts):

```typescript
// 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/main/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:

```typescript
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/main/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:

```typescript
// 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/main/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:

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

```

*Source:* [[`integration/versioning/e2e/uri-versioning.spec.ts`](https://github.com/nestjs/nest/blob/main/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`](https://github.com/nestjs/nest/blob/main/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`](https://github.com/nestjs/nest/blob/main/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`](https://github.com/nestjs/nest/blob/main/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.