qdrant-js: the JavaScript and TypeScript clients for Qdrant, package by package

Three npm packages, one repository, and a choice you have to make yourself

The repository publishes three packages. @qdrant/js-client-rest is described as a lightweight REST client for Qdrant. @qdrant/js-client-grpc is the gRPC client. @qdrant/qdrant-js is the main package with the SDK itself. The README lists them side by side but does not tell you which one to pick, and that omission is the first thing a new user runs into.

The practical reading is that the REST client is the default for most JavaScript work. It runs anywhere fetch runs, which the support section spells out as Node.js (ESM and CJS) at version 18.0.0 or above, Deno, the browser, and Cloudflare Workers with the OpenAPI client only. The gRPC package exists because Qdrant itself exposes a gRPC interface, and gRPC is a different transport with a different code generation path. If you are not sure you need it, you almost certainly want the REST package.

One caveat about the repository itself: the root package.json is private and named @qdrant/monorepo with version 0.0.0. It is a workspace root, not something you install. The engines field there requires Node >= 22.13.0 and pnpm >= 11.9.0, and that is stricter than the Node >= 18.0.0 the README gives for the published packages. Those two numbers describe different things: the first is what you need to build the monorepo from source, the second is what you need to consume the published client.

How a request actually travels: client, transport, Qdrant

You construct a client with a URL, and optionally an API key. The README shows both shapes: a local Qdrant at http://127.0.0.1:6333 with no credentials, and a Qdrant Cloud endpoint with an apiKey field. Once the client exists, you call facade methods on it. The README's example is client.getCollections(), which returns an object whose collections property you can log.

That is the whole data flow at the SDK level. The client serializes your call into a request against the Qdrant HTTP API, sends it, and returns a typed result. The TypeScript types ship alongside the JavaScript sources, so the shape of the response is visible in your editor without a separate types package.

The port in the README example is 6333, which is the HTTP port the Qdrant container exposes. The docker run command maps 6333 on the host to 6333 in the container. If you change the host-side mapping, change the URL you pass to the client to match, because the client does not discover the port.

Because the REST client is built on fetch, there is no connection pool you configure, no socket you keep open, and no client-side retry policy mentioned in the README. That is a real difference from the gRPC package, where a persistent channel is the normal model.

Installing the REST client and making your first real call

The README gives three package managers for the REST client. Pick whichever your project already uses.

pnpm i @qdrant/js-client-rest
# or
npm install @qdrant/js-client-rest
# or
yarn add @qdrant/js-client-rest

You need a Qdrant instance to talk to. The README's command starts the official container and publishes port 6333.

docker run -p 6333:6333 qdrant/qdrant

Then instantiate the client. The local form takes only a url. The cloud form takes a url and an apiKey.

import {QdrantClient} from '@qdrant/js-client-rest';

// TO connect to Qdrant running locally
const client = new QdrantClient({url: 'http://127.0.0.1:6333'});

// or connect to Qdrant Cloud
const client = new QdrantClient({
    url: 'https://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.us-east-0-1.aws.cloud.qdrant.io',
    apiKey: '<your-api-key>',
});

Now make a request using a facade method. getCollections is the smallest one that proves the wiring works.

const result = await client.getCollections();
console.log('List of collections:', result.collections);

If the connection is good, result.collections is an array of the collections that exist on that instance. On a fresh container it will be empty, which is still a successful call. If the URL is wrong you get a rejection from the fetch layer, and if the API key is wrong you get an error from Qdrant rather than from the SDK. The README points to the examples folder for more, and the repository contains examples/node-js-basic as a runnable starting point.

Version alignment with the Qdrant engine, and what that costs you

The README states the release policy directly: major and minor versions align with Qdrant's engine releases, while patch versions are reserved for fixes regarding the current minor release. New releases are cut from the master branch.

That policy has a consequence people miss. The SDK version is not free to move independently of the server. If you run Qdrant 1.18 and you want an SDK method that arrived with the 1.19 engine, upgrading the npm package alone is not the supported path. You upgrade the server too, or you stay on the older client. The recent release history shows the cadence: v1.19.0 on 2026-08-04, v1.18.0 on 2026-05-11, v1.17.0 on 2026-02-19. Roughly quarterly minor releases, tracking the engine.

For a team that pins its Qdrant deployment to a managed cloud instance, this means your SDK upgrade window is set by when that instance moves, not by when npm has a new version. Check the release notes for the version that matches your engine before you run the upgrade command, because the README does not document a compatibility matrix or a rollback procedure.

Where the SDK stops: the wrong tool for some jobs

This is a client library, not a search engine. It has no local index, no embedding model, and no vector math. If you are looking for something that generates embeddings for you, qdrant-js does not do that, and the README does not suggest it does. You bring vectors, and you bring a way to produce them.

The Cloudflare Workers support line has a qualifier worth reading twice: the README says Cloudflare Workers with OpenAPI only. That is narrower than the general browser support statement above it, and it means the full SDK surface is not what you get in that runtime. If Workers is your deployment target, verify that the specific methods you need are reachable before you design around the SDK.

The gRPC package is the other boundary. The README lists it as a published package but gives no usage example for it, no code snippet, and no transport configuration. If your reason for choosing qdrant-js is gRPC, you are working from the OpenAPI documentation and the package source rather than from the README. That is not a defect in the library, but it is a real gap in the documentation you will be reading on day one.

qdrant-js against the Python client and against raw HTTP

The obvious alternative is the Qdrant Python client, and the difference is not just language. The README's support matrix for qdrant-js includes Deno, the browser, and Cloudflare Workers. A Python client cannot run in those places at all. If your code executes at the edge or in a browser tab, the JavaScript SDK is the only one of the two that is even eligible.

The other alternative is skipping the SDK and calling the Qdrant HTTP API directly with fetch. That is a legitimate choice, and it is what the REST client is doing underneath. The trade you make is types. The README states that TypeScript types are provided alongside the JavaScript sources, so with the SDK your request and response shapes are checked at compile time. With raw fetch you maintain those shapes yourself, and you are the one who notices when the engine's API changes. For a small number of calls, raw fetch is less machinery. For a service that touches a dozen Qdrant endpoints, the typed facade is the reason the package exists.

The gRPC package sits between those options: it is still the SDK, but it is a different transport with its own dependency footprint and, in the README at least, no example to copy from.

Licence, contribution model, and the cost of keeping up

The repository is Apache-2.0. That is a permissive licence, and it is the same identifier the README's badge links to. Nothing in the README adds terms on top of it, but the README is not a licence document, so read LICENSE in the repository if your organisation has specific requirements around attribution or patent grants.

The contribution model is a pnpm monorepo. CONTRIBUTING.md is the entry point, and the README says the project uses pnpm instead of npm or yarn to manage and install packages, so pnpm install at the root installs dependencies for the whole workspace and runs the compilation steps. The root package.json pins packageManager to pnpm@11.9.0 and requires pnpm >= 11.9.0, so a mismatched pnpm will not behave the way the maintainers expect. The README notes that for anything outside the monorepo, such as examples/node-js-basic, npm is fine.

Upgrade cost is mostly the version alignment issue. If you track Qdrant Cloud, your SDK upgrades follow the engine. If you self-host, you control both sides and can move them together. The last push to the repository was on 2026-09-10, and the repository is not archived, so the codebase is being worked on. The README does not describe a deprecation policy for facade methods, which means a method you depend on could change shape at a minor release without a documented migration path.

Editorial conclusion

Adopt @qdrant/js-client-rest if you are writing a Node, Deno, browser or Cloudflare Workers service that talks to a Qdrant instance over HTTP and you want the smallest surface to reason about. Do not adopt it if you need server-side streaming or bidirectional calls that only gRPC exposes, or if your runtime cannot satisfy the Node >= 18.0.0 support line the README states for the published packages. Before you commit, check the release notes for the version that matches your Qdrant engine, then confirm that the facade method you depend on exists in the package you installed rather than in a sibling package.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. qdrant/qdrant-js on GitHub
4. README
5. Releases