Getting Started

This section offers jumping off points for how to get started using NestJS AI.

You should follow the steps in each of the following sections according to your needs.

NestJS AI targets NestJS 10+ or 11+ (peer dependency range ^10.0.0 || ^11.0.0) and requires Node.js 22.12.0 or later, matching the engines.node constraint in package.json.

Installation

NestJS AI packages are published to the npm registry under the @nestjs-ai/* scope. No additional registry configuration is required — the default npm registry is used.

Install the platform package together with the chat model(s) and clients you need, along with their declared peer dependencies. A minimal ChatClient application using OpenAI looks like this:

pnpm add @nestjs-ai/platform @nestjs-ai/model-openai @nestjs-ai/client-chat \
  @nestjs-ai/commons @nestjs-ai/model \
  @nestjs-port/core @nestjs/common @nestjs/core \
  rxjs zod openai
The @nestjs-ai/* and @nestjs-port/core packages are declared as peers so that the host application controls their version. @nestjs/common and @nestjs/core are typically already present in a NestJS project; openai is required by @nestjs-ai/model-openai, and zod / rxjs are used throughout the API surface. @azure/identity is an optional peer of @nestjs-ai/model-openai — install it only if you need Azure AD authentication.

Additional feature packages can be added on top (see Add dependencies for specific components).

Module Configuration

NestJS AI uses NestJS dynamic modules instead of Spring Boot auto-configuration. Every feature (HTTP client, chat model, embedding model, vector store, client builder, …​) must be explicitly imported into your module graph.

Module Dependency Chain

Modules must be imported in an order that satisfies their token dependencies:

  1. NestAiModule.forRoot() — must be imported first. Provides HTTP_CLIENT_TOKEN.

  2. A chat model module (e.g. OpenAiChatModelModule.forFeature()) — requires HTTP_CLIENT_TOKEN, provides CHAT_MODEL_TOKEN.

  3. ChatClientModule.forFeature() — requires CHAT_MODEL_TOKEN, provides CHAT_CLIENT_BUILDER_TOKEN (transient).

Basic Setup

import { Module } from '@nestjs/common';
import { NestAiModule } from '@nestjs-ai/platform';
import { InjectChatModel } from '@nestjs-ai/platform/decorators';
import { OpenAiChatModelModule } from '@nestjs-ai/model-openai';
import { ChatClientModule } from '@nestjs-ai/client-chat';

@Module({
  imports: [
    NestAiModule.forRoot(),
    OpenAiChatModelModule.forFeature({
      apiKey: process.env.OPENAI_API_KEY,
      options: {
        model: 'gpt-4o-mini',
        temperature: 0.7,
      },
    }),
    ChatClientModule.forFeature(),
  ],
})
export class AppModule {}

Async Configuration

For dynamic configuration (e.g. loading API keys via ConfigService or environment):

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { NestAiModule } from '@nestjs-ai/platform';
import { OpenAiChatModelModule } from '@nestjs-ai/model-openai';
import { ChatClientModule } from '@nestjs-ai/client-chat';

@Module({
  imports: [
    ConfigModule.forRoot(),
    NestAiModule.forRoot(),
    OpenAiChatModelModule.forFeatureAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        apiKey: config.get<string>('OPENAI_API_KEY'),
        options: {
          model: 'gpt-4o-mini',
          temperature: 0.7,
        },
      }),
    }),
    ChatClientModule.forFeature({
      customizer: (builder) => {
        builder.defaultSystem('You are a helpful assistant.');
      },
    }),
  ],
})
export class AppModule {}

Using the ChatClient

Use InjectChatModel() from @nestjs-ai/platform and create a ChatClient with ChatClient.create(chatModel), or inject the transient CHAT_CLIENT_BUILDER_TOKEN provided by ChatClientModule to reuse the configured builder.

// chat.controller.ts
import { Controller, Get, Query } from '@nestjs/common';
import { ChatClient } from '@nestjs-ai/client-chat';
import { InjectChatModel } from '@nestjs-ai/platform';
import type { ChatModel } from '@nestjs-ai/model';

@Controller()
export class ChatController {
  private readonly chatClient: ChatClient;

  constructor(@InjectChatModel() chatModel: ChatModel) {
    this.chatClient = ChatClient.create(chatModel);
  }

  @Get('/ai')
  async generation(
    @Query('userInput') userInput: string,
  ): Promise<string | null> {
    return this.chatClient.prompt().user(userInput).call().content();
  }
}

Bootstrap the application as usual:

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
void bootstrap();

Module Options

NestAiModule.forRoot(options?) (from @nestjs-ai/platform)

Property Type Default Description

httpClient

HttpClient

FetchHttpClient

Custom HTTP client implementation used by all model modules.

imports

ModuleMetadata['imports']

[]

Additional modules imported into the root module.

global

boolean

true

Whether to register the module globally.

OpenAiChatModelModule.forFeature(properties, options?) (from @nestjs-ai/model-openai)

Property Type Default Description

apiKey

string

—

OpenAI API key.

baseUrl

string

—

Custom base URL (proxies, compatible providers, Microsoft Foundry, GitHub Models).

organizationId

string

—

Organization ID.

deploymentName

string

—

Deployment name (Microsoft Foundry).

model

string

—

Default model name at the connection level.

timeout

Milliseconds

60000

Request timeout.

maxRetries

number

3

Maximum retries for transient failures.

customHeaders

Record<string, string>

—

Additional HTTP headers applied to every request.

options.model

string

gpt-5-mini

Default chat model (OPEN_AI_CHAT_DEFAULT_MODEL).

options.temperature

number

—

Sampling temperature (0.0–2.0).

options.maxTokens

number

—

Maximum tokens in a response.

options.topP

number

—

Nucleus sampling parameter.

options.frequencyPenalty

number

—

Frequency penalty (-2.0–2.0).

options.presencePenalty

number

—

Presence penalty (-2.0–2.0).

options.stop

string[]

—

Stop sequences.

options.seed

number

—

Random seed for deterministic output.

options.n

number

—

Number of completions to generate.

toolCalling

ToolCallingObservationProperties

—

Tool-calling observation settings.

ChatClientModule.forFeature(options?) (from @nestjs-ai/client-chat)

Property Type Default Description

customizer

(builder: ChatClient.Builder) ⇒ void

—

Callback used to configure the shared builder (e.g. default system prompts, default advisors).

imports

ModuleMetadata['imports']

[]

Additional modules imported into the feature module.

global

boolean

false

Whether to register the module globally.

Add dependencies for specific components

Each of the following sections in the documentation shows which dependencies you need to add to your project:

NestJS AI samples

Sample applications demonstrating how to use NestJS AI are maintained in the nestjs-ai-examples repository.