Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpensearchModule
✓ import { OpensearchModule } from 'nestjs-opensearch';
✗ const OpensearchModule = require('nestjs-opensearch').OpensearchModule;
The main NestJS module for configuring and registering OpenSearch clients.
InjectOpensearchClient
✓ import { InjectOpensearchClient } from 'nestjs-opensearch';
✗ import InjectOpensearchClient from 'nestjs-opensearch';
Decorator used to inject `OpensearchClient` instances into services or controllers. Supports named clients.
OpensearchClient
✓ import { OpensearchClient } from 'nestjs-opensearch';
The TypeScript type definition for the injected OpenSearch client. It corresponds to the client from `@opensearch-project/opensearch`.
OpensearchClientOptionsFactory
✓ import { OpensearchClientOptionsFactory } from 'nestjs-opensearch';
Interface to implement when using `forRootAsync({ useClass: ... })` for custom asynchronous client option provisioning.
This quickstart demonstrates how to configure default and named OpenSearch clients asynchronously using `ConfigModule` and `useFactory`. It then shows how to inject these clients into a service (`SearchService`) to perform basic indexing and searching operations, illustrating a typical NestJS integration pattern.
import { Module, Injectable } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { OpensearchModule, InjectOpensearchClient, OpensearchClient } from 'nestjs-opensearch';
// A basic configuration factory for NestJS ConfigModule
function configuration() {
return {
opensearch: {
node: process.env.OPENSEARCH_NODE || 'http://localhost:9200',
auth: {
username: process.env.OPENSEARCH_USERNAME || 'admin',
password: process.env.OPENSEARCH_PASSWORD || 'admin'
}
}
};
}
@Injectable()
export class SearchService {
constructor(
// Inject the default client (no clientName specified)
@InjectOpensearchClient() private readonly defaultClient: OpensearchClient,
// Inject a named client
@InjectOpensearchClient('myNamedClient') private readonly namedClient: OpensearchClient,
) {}
async indexDocument(index: string, id: string, document: any): Promise<void> {
await this.defaultClient.index({
index,
id,
body: document,
refresh: true,
});
console.log(`Document '${id}' indexed successfully using the default client.`);
}
async searchDocuments(index: string, query: any): Promise<any[]> {
const { body } = await this.namedClient.search({
index,
body: { query },
});
console.log(`Search performed on '${index}' using 'myNamedClient'.`);
return body.hits.hits;
}
}
@Module({
imports: [
// Load configuration for the application
ConfigModule.forRoot({
load: [configuration],
isGlobal: true,
}),
// Configure the default OpenSearch client asynchronously
OpensearchModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
node: configService.get<string>('opensearch.node'),
auth: configService.get<{ username: string; password: string }>('opensearch.auth'),
}),
}),
// Configure a named OpenSearch client asynchronously
OpensearchModule.forRootAsync({
clientName: 'myNamedClient',
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
node: configService.get<string>('opensearch.node'),
auth: configService.get<{ username: string; password: string }>('opensearch.auth'),
}),
}),
],
providers: [SearchService],
exports: [SearchService],
})
export class AppModule {}
// To bootstrap and run this application:
// import { NestFactory } from '@nestjs/core';
// async function bootstrap() {
// const app = await NestFactory.create(AppModule);
// await app.listen(3000);
// const searchService = app.get(SearchService);
// await searchService.indexDocument('my-test-index', 'doc1', { title: 'Hello World' });
// const results = await searchService.searchDocuments('my-test-index', { match_all: {} });
// console.log('Search results:', results);
// }
// bootstrap();
Errors
Common errors & fixes
Error: Nest can't resolve dependencies of the OpensearchService (?). Please make sure that the argument OpensearchClient at index [0] is available in the SearchModule context.
The `OpensearchModule` was not correctly imported or configured in the NestJS module where `OpensearchService` is provided or injected.
fixEnsure `OpensearchModule.forRoot(...)` or `OpensearchModule.forRootAsync(...)` is added to the `imports` array of the respective NestJS module (e.g., `AppModule`).
TypeError: (0 , nestjs_opensearch_1.OpensearchModule).forRootAsync is not a function
This usually indicates attempting to call `forRootAsync` with an array of configurations after it was deprecated, or a mismatch in how the method is expected to be called.
fixSince v0.3.0, `forRootAsync` no longer accepts an array. Call `OpensearchModule.forRootAsync()` separately for each individual client configuration. Also, verify you are using a compatible version of the library.
Error: Cannot find module '@opensearch-project/opensearch' or its corresponding type declarations.
The core `@opensearch-project/opensearch` client library, a peer dependency, has not been installed in your project.
fixInstall the necessary peer dependency: `npm install @opensearch-project/opensearch` or `yarn add @opensearch-project/opensearch`.
OpensearchClientError: No Living connections
The OpenSearch client failed to establish a connection to the specified node(s). This can be due to an incorrect node URL, network issues, or authentication failures.
fixVerify the `node` URL(s) provided in `OpensearchModule` configuration (e.g., `http://localhost:9200`). Check network connectivity to the OpenSearch cluster and ensure any authentication credentials (username, password, API key) are correct.
Audit
Dependencies
@nestjs/commonrequiredCore NestJS framework peer dependency, required for module registration and dependency injection.
@opensearch-project/opensearchrequiredThe official OpenSearch client library, which this module wraps and exposes.