meilisearch-js

Meilisearch JS is the official client library for Meilisearch, the open-source, typo-tolerant search engine, giving JavaScript and TypeScript developers a fully typed wrapper around every Meilisearch REST endpoint: indexes, documents, search, settings, tasks, batches, API keys, and tenant tokens. It ships as a dependency-free ESM package targeting modern Node.js and browser runtimes, relying entirely on native fetch, Headers, AbortController, and Web Crypto instead of pulling in a userland HTTP client or JWT library.

Beyond raw request wrapping, the client adds real developer-experience conveniences: mutating calls return an enqueued task object that can be awaited directly for completion instead of requiring a separate polling loop, requests can be routed through a custom HTTP client (for proxying or using axios) via configuration, and tenant tokens for scoped, filtered search access are signed client-side with the Web Crypto API. The project is maintained directly by Meilisearch and tested against real Meilisearch server instances via Docker Compose rather than mocks.

What You Get

• A typed Meilisearch client class exposing index management, document CRUD, search, settings, and API key operations
• Awaitable enqueued-task objects returned from mutating calls, avoiding manual task-status polling for common operations
• Client-side tenant token generation (HMAC-signed, JWT-style) for scoping search access by API key and filter rules without a server round-trip
• A typed error hierarchy (MeilisearchApiError, MeilisearchRequestError, MeilisearchRequestTimeoutError, MeilisearchTaskTimeoutError) instead of generic thrown errors
• Zero runtime dependencies, ESM-only distribution, and support for custom HTTP clients/proxies via configuration

Common Use Cases

• Adding instant, typo-tolerant search to a JavaScript/TypeScript web or Node.js application
• Building faceted search and filtering UIs backed by a self-hosted or Meilisearch Cloud instance
• Generating scoped tenant tokens so front-end clients can search with restricted, per-user visibility
• Managing index lifecycle and settings (filterable/sortable/searchable attributes) programmatically from application or migration code
• Tracking long-running indexing/document-import tasks to completion within CI pipelines or admin tooling

Under The Hood

Architecture The client is organized around a slim Meilisearch facade (src/meilisearch.ts) that owns a shared HttpRequests transport (src/http-requests.ts) and exposes lazily-instantiated getters for a TaskClient (src/task.ts) and BatchClient (src/batch.ts), while index()/getIndex() hand back Index instances (src/indexes.ts) that carry their own config and issue requests through that same shared transport — a flat, delegation-based structure rather than a layered one. All requests funnel through http-requests.ts, which centralizes header construction (an X-Meilisearch-Client agent string pulled from package.json), timeout handling via custom AbortController composition, and typed error translation. Mutating calls return EnqueuedTask objects wrapped by a helper that lets callers await task completion directly rather than manually polling tasks.waitForTask. Swapping the core HTTP abstraction would touch every method on Index and Meilisearch, since none of them own their own fetch logic.

Tech Stack The package targets modern runtimes only (Node “^20.19.0 || >=22.12.0”), ships as ESM-only with zero runtime dependencies, and relies entirely on native fetch, Headers, AbortController, and crypto.subtle (used for HMAC-signed tenant tokens in src/token.ts). The dev toolchain is a pnpm workspace using Vite for building/bundling, TypeScript in strict mode, Vitest with coverage-v8 for testing, oxlint (type-aware) plus Prettier enforced via Husky and lint-staged, and TypeDoc with a VitePress theme to generate and publish API reference docs. A Docker Compose setup and dedicated GitHub Actions workflows run the suite against real Meilisearch server versions.

Code Quality Tests are organized as one spec file per feature area (documents, facet search, embedders, tasks, keys, tokens, pagination, and more) using Vitest’s parameterized suites to exercise Master/Admin/Search permission levels against a live Meilisearch instance rather than mocks, giving strong confidence the client matches real server behavior. Errors are modeled as a typed hierarchy rather than thrown as plain errors or swallowed. The codebase is fully typed TypeScript enforced via strict type-checking and type-aware linting, with CI running lint, type-check, and tests on every change, and a repository AGENTS.md documenting the expected contributor workflow.

API Design The public API mirrors Meilisearch’s REST resources closely (client.index(uid).search(), .addDocuments(), .updateFilterableAttributes()), so most of the learning curve comes from Meilisearch’s own API docs rather than library-specific abstractions. Mutating calls return promise-like enqueued-task objects that can be awaited directly or inspected immediately for a task UID, removing a separate manual-polling step for the common case. Tenant token generation implements HMAC-signed, JWT-style tokens client-side using Web Crypto rather than pulling in a JWT dependency, and a configurable custom-HTTP-client escape hatch lets consumers proxy requests without forking the library — practical ergonomics rather than a groundbreaking technical novelty.