ClickHouse JS

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/language-clients/js.md)

The official JS client for connecting to ClickHouse.
The client is written in TypeScript and provides typings for the client public API.

It has zero dependencies, is optimized for maximum performance, and is tested with various ClickHouse versions and configurations (on-premise single node, on-premise cluster, and ClickHouse Cloud).

There are two different versions of the client available for different environments:

- `@clickhouse/client` - Node.js only
- `@clickhouse/client-web` - browsers (Chrome/Firefox), Cloudflare workers

When using TypeScript, make sure it is at least [version 4.5](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html), which enables [inline import and export syntax](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names).

The client source code is available in the [ClickHouse-JS GitHub repository](https://github.com/ClickHouse/clickhouse-js).

## Environment requirements (node.js)[​](#environment-requirements-nodejs "Direct link to Environment requirements (node.js)")

Node.js must be available in the environment to run the client.
The client is compatible with all the [maintained](https://github.com/nodejs/release#readme) Node.js releases.

As soon as a Node.js version approaches End-Of-Life, the client drops support for it as it is considered outdated and insecure.

Current Node.js versions support:

|  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Node.js version Supported?|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | 24.x ✔|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | 22.x ✔|  |  |  |  | | --- | --- | --- | --- | | 20.x ✔|  |  | | --- | --- | | 18.x Best effort | | | | | | | | | |

## Environment requirements (web)[​](#environment-requirements-web "Direct link to Environment requirements (web)")

The web version of the client is officially tested with the latest Chrome/Firefox browsers and can be used as a dependency in, for example, React/Vue/Angular applications, or Cloudflare workers.

## Installation[​](#installation "Direct link to Installation")

To install the latest stable Node.js client version, run:

```
npm i @clickhouse/client
```

Web version installation:

```
npm i @clickhouse/client-web
```

## Compatibility with ClickHouse[​](#compatibility-with-clickhouse "Direct link to Compatibility with ClickHouse")

|  |  |  |  |
| --- | --- | --- | --- |
| Client version ClickHouse|  |  | | --- | --- | | 1.12.0 24.8+ | | | |

Likely, the client will work with the older versions, too; however, this is best-effort support and isn't guaranteed. If you have a ClickHouse version older than 23.3, please refer to [ClickHouse security policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) and consider upgrading.

## Examples[​](#examples "Direct link to Examples")

We aim to cover various scenarios of client usage with the [examples](https://github.com/ClickHouse/clickhouse-js/blob/main/examples) in the client repository.

The overview is available in the [examples README](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/README.md#overview).

If something is unclear or missing from the examples or from the following documentation, feel free to [contact us](/docs/integrations/javascript#contact-us).

### Client API[​](#client-api "Direct link to Client API")

Most of the examples should be compatible with both Node.js and web versions of the client, unless explicitly stated otherwise.

#### Creating a client instance[​](#creating-a-client-instance "Direct link to Creating a client instance")

You can create as many client instances as necessary with the `createClient` factory:

```
import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'

const client = createClient({
  /* configuration */
})
```

If your environment doesn't support ESM modules, you can use CJS syntax instead:

```
const { createClient } = require('@clickhouse/client');

const client = createClient({
  /* configuration */
})
```

A client instance can be [pre-configured](/docs/integrations/javascript#configuration) during instantiation.

#### Configuration[​](#configuration "Direct link to Configuration")

When creating a client instance, the following connection settings can be adjusted: