# typesense

> Javascript Library for Typesense

Latest version **3.0.6** (published 2026-04-21) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install typesense
pnpm add typesense
yarn add typesense
bun add typesense
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.0.6 |
| Published | 2026-04-21 |
| First published | 2018-04-04 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 2.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 569 |
| Author | Typesense, Inc. |
| Maintainers | jasonbosco, kishorenc, tharropoulos, haydenhoang |
| Keywords | typesense, api, sdk, client, wrapper, server, search |

## Links

- npm: https://www.npmjs.com/package/typesense
- Repository: https://github.com/typesense/typesense-js
- Issues: https://github.com/typesense/typesense-js/issues
- npm.io page: https://npm.io/package/typesense

## Dependencies (3)

- [axios](https://npm.io/package/axios.md) ^1.15.0
- [tslib](https://npm.io/package/tslib.md) ^2.8.1
- [loglevel](https://npm.io/package/loglevel.md) ^1.9.2

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 3.0.6 (latest) — 2026-04-21
- 3.0.7-1 (next) — 2026-08-31
- 3.0.7-0 — 2026-04-21
- 3.0.5 — 2026-03-31
- 3.0.4 — 2026-03-26
- 3.0.3 — 2026-03-13
- 3.0.2 — 2026-03-05
- 3.0.1 — 2026-02-06
- 3.0.0-2 — 2025-09-25
- 3.0.0-1 — 2025-09-10
- 3.0.0-0 — 2025-08-20
- 2.1.0 — 2025-08-20
- 2.1.0-13 — 2025-07-23
- 2.1.0-12 — 2025-07-15
- 2.1.0-11 — 2025-07-14
- … 188 more at https://npm.io/package/typesense/versions

## README

# typesense-js [![NPM version][npm-image]][npm-url] ![downloads](https://img.shields.io/npm/dt/typesense?label=downloads)

Javascript client library for accessing the [Typesense HTTP API](https://github.com/typesense/typesense).

This library can be used both on the server-side and on the client-side. The library's [source](/src) is in ES6 and during build time, we transpile it to ES5 and generate two artifacts - [one](/lib) that can be used on the server-side and [another](/dist) that uses [Browserify](http://browserify.org/) and can be used on the client side.

## Installation

#### Option 1: Install via npm

```sh
npm install --save typesense
```

Install peer dependencies:
```sh
npm install --save @babel/runtime
```

Note: `@babel/runtime` is very a common dependency among many JS libraries. So instead of each library adding it as a dependency independently (which will cause multiple instances of `@babel/runtime` to be installed increasing bundle size), Babel's recommendation is that the libraries ask users to install it once as a direct dependency, so there's only one copy of `@babel/runtime` for the entire project. In some cases, your JS framework might already include `@babel/runtime` as a dependency.

#### Option 2: Include the minified JS file for use in the browser directly

```html
<script src="dist/typesense.min.js"></script>
```

or via jsDelivr

```html
<script src="https://cdn.jsdelivr.net/npm/typesense@3/dist/typesense.min.js"></script>
```

## Usage

Read the documentation here for detailed examples: [https://typesense.org/docs/api/](https://typesense.org/docs/api/)

Tests are also a good place to know how the library works internally: [test](test)

**Note: When using this library in a browser, please be sure to use an API Key that only allows search operations instead of the `master` API key.** See [doc/examples/server/keys.js](doc/examples/server/keys.js) for an example of how to generate a search only API key.

See [Configuration.ts](src/Typesense/Configuration.ts) for a list of all client configuration options.

### Request Timeouts and Abort Signals

The client supports both global timeout configuration and per-request abort signals:

#### Global Timeout Configuration

```javascript
const client = new Typesense.Client({
  nodes: [{ host: "localhost", port: "8108", protocol: "http" }],
  apiKey: "xyz",
  connectionTimeoutSeconds: 30, // 30 second timeout for all requests
});
```

#### Per-Request Abort Signals

```javascript
// Search with 5-second timeout
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const results = await client.collections("books").documents().search(
  {
    q: "*",
    query_by: "title",
  },
  { abortSignal: controller.signal },
);

// Collections with 2-second timeout
const collectionsController = new AbortController();
setTimeout(() => collectionsController.abort(), 2000);

const collections = await client.collections().retrieve({
  abortSignal: collectionsController.signal,
});
```

**Note**: The `import()` operation doesn't support abort signals or timeout configuration as it's designed to run to completion.

### Examples

Here are some examples with inline comments that walk you through how to use the client: [doc/examples](doc/examples)

To run the examples, from the repo root:

```bash
npm run typesenseServer
node doc/examples/server/bulkImport.js
```

## GatsbyJS Integration

If you use [GatsbyJS](https://www.gatsbyjs.com/) for a framework, we have a plugin (that uses typesense-js behind the scenes) to automatically push your site data to Typesense when you build your site. Learn more [here](https://github.com/typesense/gatsby-plugin-typesense).

## Firebase Integration

If you use [Firebase](https://firebase.google.com/), we have a Firebase extension (that uses typesense-js behind the scenes) to automatically push your Firestore data to Typesense. Learn more [here](https://github.com/typesense/firestore-typesense-search).

## Building UI components

Checkout the [Typesense-InstantSearch.js](https://github.com/typesense/typesense-instantsearch-adapter) (which uses typesense-js) for UI components you can use to quickly build powerful instant search experiences.

## Compatibility

This table refers to server=>client compatibility. Newer versions of the client library maintain backwards compatibility with older versions of the server library.

| Typesense Server | typesense-js |
|------------------|--------------|
| \>= v30.0        | \>= v3.0.0   |
| \>= v27.0.rc20   | \>= v2.0.0   |
| \>= v0.26.0.rc38 | \>= v1.8.0   |
| \>= v0.25.0      | \>= v1.7.0   |
| \>= v0.24.0      | \>= v1.5.0   |
| \>= v0.23.0      | \>= v1.3.0   |
| \>= v0.21.0      | \>= v0.14.0  |
| \>= v0.20.0      | \>= v0.12.0  |
| \>= v0.19.0      | \>= v0.11.0  |
| \>= v0.18.0      | \>= v0.10.0  |
| \>= v0.17.0      | \>= v0.9.0   |
| \>= v0.16.0      | \>= v0.8.0   |
| \>= v0.15.0      | \>= v0.7.0   |
| \>= v0.12.1      | \>= v0.5.0   |
| \>= v0.12.0      | \>= v0.4.7   |
| <= v0.11         | <= v0.3.0    |

## Development

After checking out the repo, run `npm install` to install dependencies. Then run `npm run test:local` to run the linter and tests.

To release a new version, we use the [np](https://github.com/sindresorhus/np) package:

```shell
$ npm install --global np
$ np

# Follow instructions that np shows you

```

## Contributing

Bug reports and pull requests are welcome on GitHub at [https://github.com/typesense/typesense-js](https://github.com/typesense/typesense-js).

[npm-image]: https://badge.fury.io/js/typesense.svg
[npm-url]: https://npmjs.org/package/typesense

---
_Source: https://npm.io/package/typesense · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._