Setup

clickhouse-js Repository Setup

Use this skill before running any of the npm run test:*, npm run lint, npm run typecheck, or npm run build scripts in a fresh checkout (or after pulling changes that touch package.json files).

Prerequisites

• Node.js 22 recommended (matches .nvmrc). The root package.json declares "engines": { "node": ">=20.19.0" }, and CI tests Node 20, 22, 24, and 26.
• Docker with the Compose plugin (docker compose ...). Required only for integration tests and any example that talks to a real server.

1. Install dependencies

This is an npm workspaces repo (packages/*), with two additional independent example packages (examples/node, examples/web) that have their own package.json and are not part of the workspaces.

Install all three:

npm install
npm --prefix examples/node install
npm --prefix examples/web install

The root postinstall script patches node_modules/parquet-wasm/package.json; it runs automatically as part of npm install.

2. Build the workspace packages

The workspace packages (@clickhouse/client-common, @clickhouse/client, @clickhouse/client-web) must be built before some tests, examples, and typechecks can resolve their inter-package imports:

npm run build

This runs build in every workspace package.

3. Start ClickHouse (only for integration tests / examples)

Unit tests do not need a server. Integration tests (npm run test:*:integration*) and the example runners do.

From the repo root:

docker compose up -d

This starts both the single-node setup (clickhouse on 8123/9000, clickhouse_tls on 8443/9440) and the two-node cluster (clickhouse1, clickhouse2, plus the nginx round-robin entrypoint on 8127). All services use non-overlapping ports so a single up -d covers every integration test mode.

To override the server version, set CLICKHOUSE_VERSION when starting Compose; for example: CLICKHOUSE_VERSION=head docker compose up -d, CLICKHOUSE_VERSION=latest docker compose up -d, or CLICKHOUSE_VERSION=24.8 docker compose up -d to use an explicit version tag.

4. Verify

After the steps above you can run, for example:

• npm run lint — lint every workspace package
• npm run typecheck — typecheck every workspace package
• npm run test:node:unit / npm run test:web:unit — unit tests, no server required
• npm run test:node:integration / npm run test:web:integration — integration tests, server required
• From examples/node or examples/web: npm run lint, npm run typecheck, npm run run-examples

See npm run from the repo root for the full list of test scripts.