4. Create a shared client singleton at src/lib/esClient.ts (see examples below).

5. Import from your vendor path or use the path alias configured above throughout your application.

Public API

Client

import { Client } from './vendor/elasticsearch/index'

const client = new Client({
  node: string | string[],
  auth?: { apiKey: string } | { username: string; password: string } | { bearer: string },
  tls?: TlsConnectionOptions,
  maxRetries?: number,
  requestTimeout?: number,
  compression?: boolean,
})

The central class for all Elasticsearch interactions. Instantiate it once with your cluster URL and credentials. Every API namespace (client.search, client.indices, client.bulk, etc.) is attached to this instance. Use it as a long-lived singleton — it manages an internal connection pool.

SniffingTransport

import { SniffingTransport } from './vendor/elasticsearch/index'

const client = new Client({
  node: 'https://seed-node:9200',
  Transport: SniffingTransport,
  sniffOnStart: true,
  sniffInterval: 30000,
})

A drop-in transport replacement that periodically queries the cluster for live node addresses and adds them to the connection pool. Use this when your Elasticsearch cluster topology changes dynamically (e.g., autoscaling deployments). Pass it via the Transport option on Client.

estypes

import { estypes } from './vendor/elasticsearch/index'

const query: estypes.QueryDslQueryContainer = {
  match: { title: { query: 'typescript' } }
}

const response: estypes.SearchResponse<MyDoc> = await client.search({ ... })

The full Elasticsearch type namespace, automatically generated from the official OpenAPI spec. Use these types to annotate request bodies, query DSL objects, and response shapes for end-to-end type safety without writing your own interfaces.

Working examples

Scenario - Connect and index a document

A minimal singleton client that indexes a typed document into Elasticsearch using the index API.

import { Client } from './vendor/elasticsearch/index'
import type { estypes } from './vendor/elasticsearch/index'

interface Article {
  title: string
  body: string
  publishedAt: string
}

const client = new Client({
  node: process.env.ELASTICSEARCH_URL ?? 'http://localhost:9200',
  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY ?? '' },
})

async function indexArticle(article: Article): Promise<void> {
  const response = await client.index<Article>({
    index: 'articles',
    document: article,
  })
  console.log(`Indexed document id: ${response._id}`)
}

indexArticle({
  title: 'Getting started with TypeScript',
  body: 'TypeScript adds static types to JavaScript...',
  publishedAt: new Date().toISOString(),
})

Scenario - Full-text search with typed results

Run a multi-field full-text search and extract typed hits from the response.

import { Client, estypes } from './vendor/elasticsearch/index'

interface Product {
  name: string
  description: string
  price: number
}

const client = new Client({
  node: process.env.ELASTICSEARCH_URL!,
  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
})

async function searchProducts(query: string): Promise<Product[]> {
  const response = await client.search<Product>({
    index: 'products',
    query: {
      multi_match: {
        query,
        fields: ['name^3', 'description'],
      },
    },
    size: 10,
  })

  return response.hits.hits
    .filter((hit) => hit._source !== undefined)
    .map((hit) => hit._source as Product)
}

searchProducts('noise cancelling headphones').then(console.log)

Scenario - Bulk indexing with SniffingTransport

Use SniffingTransport for a dynamic cluster and the bulk API to efficiently index thousands of records.

import { Client, SniffingTransport } from './vendor/elasticsearch/index'

interface LogEvent {
  level: string
  message: string
  timestamp: string
  service: string
}

const client = new Client({
  node: process.env.ELASTICSEARCH_URL!,
  auth: { apiKey: process.env.ELASTICSEARCH_API_KEY! },
  Transport: SniffingTransport,
  sniffOnStart: true,
})

async function bulkIndexLogs(events: LogEvent[]): Promise<void> {
  const operations = events.flatMap((event) => [
    { index: { _index: 'logs' } },
    event,
  ])

  const response = await client.bulk({ operations, refresh: true })

  if (response.errors) {
    const failed = response.items.filter((i) => i.index?.error)
    console.error(`${failed.length} operations failed`)
  } else {
    console.log(`Indexed ${events.length} log events`)
  }
}

bulkIndexLogs([
  { level: 'info', message: 'Server started', timestamp: new Date().toISOString(), service: 'api' },
  { level: 'warn', message: 'High latency detected', timestamp: new Date().toISOString(), service: 'api' },
])

File walkthrough

• index.ts - Package entry point; exports Client, SniffingTransport, all @elastic/transport classes and types, and the estypes namespace.
• client.ts - Implements the Client class, wiring together transport, serializer, connection pool, and the generated API methods.
• sniffingTransport.ts - Extends the base Transport to add periodic node sniffing for dynamic cluster discovery.
• helpers.ts - Convenience wrappers around low-level APIs: bulk helper, scroll/async iterator helper, and MSEARCH helper.
• symbols.ts - Private Symbol keys used internally by the client to attach metadata to requests without polluting public interfaces.
• api/index.ts - Auto-generated file that imports every API namespace class and mixes them into the Client prototype.
• api/api/ - One TypeScript file per top-level Elasticsearch API group (search.ts, indices.ts, bulk.ts, ml.ts, etc.), each exporting a function or class of typed request/response methods.

Common pitfalls and fixes

• Node.js version below v20: The client explicitly requires Node.js v20+; running on older versions causes runtime errors. Fix: upgrade Node.js or use nvm use 20.
• Missing @elastic/transport peer: The source imports directly from @elastic/transport; omitting it causes module-not-found errors at runtime. Fix: npm install @elastic/transport.
• API key vs. username/password mismatch: Passing { apiKey: '' } with an empty string silently sends invalid auth headers. Fix: guard with process.env.ELASTICSEARCH_API_KEY ?? undefined and omit the auth key if absent.
• ESM/CJS interop with tslib: If your project uses "type": "module" in package.json, ensure tslib is resolvable as ESM or set "esModuleInterop": true in tsconfig. Fix: add "esModuleInterop": true and "allowSyntheticDefaultImports": true.
• TLS certificate errors against local clusters: Self-signed certs on local Elasticsearch instances reject by default. Fix: pass tls: { rejectUnauthorized: false } in the Client options during development only.
• estypes used as a value instead of a type: estypes is a type namespace; importing it without import type in strict ESM will fail tree-shaking. Fix: use import { estypes } from '...' for types inline, or import type { estypes } if only used as types.

Vibe-coding prompt template

I have the Elasticsearch Node.js client source code in `src/vendor/elasticsearch/`
and a usage guide at `USAGE.md`. The upstream npm package is `@elastic/elasticsearch@9.4.0`.

Please help me integrate this into my existing Node.js/TypeScript project by:

1. Reading `USAGE.md` fully to understand the available exports and patterns.
2. Creating a singleton `Client` instance in `src/lib/esClient.ts` using environment
   variables for the node URL and API key.
3. Adding typed search and indexing functions for my domain model (describe it to the AI).
4. Wiring the client into my Express/Fastify/NestJS routes.
5. Ensuring all imports reference `src/vendor/elasticsearch/index.ts` and that
   `tsconfig.json` is configured correctly per the USAGE.md setup steps.
6. Using the `estypes` namespace for all request and response type annotations.

Do not install the npm package directly; use the local source at `src/vendor/elasticsearch/`.
Show each file you create or modify, with full content.

License and credit

The source is licensed under the Apache-2.0 license (see source/ files for the SPDX header SPDX-License-Identifier: Apache-2.0). Upstream package: @elastic/elasticsearch by Elasticsearch B.V. Source repository: https://github.com/elastic/elasticsearch-js.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

OpenSearch JavaScript Client for Node.js

Automation, Utilities & Developer Tools

Free