Manual Installation

Install the runtime packages

Install the core packages required to run hypequery:

npm install @hypequery/clickhouse @hypequery/serve

# Optional: install the CLI locally
npm install -D @hypequery/cli

pnpm add @hypequery/clickhouse @hypequery/serve

# Optional: install the CLI locally
pnpm add -D @hypequery/cli

yarn add @hypequery/clickhouse @hypequery/serve

# Optional: install the CLI locally
yarn add -D @hypequery/cli

bun add @hypequery/clickhouse @hypequery/serve

# Optional: install the CLI locally
bun add -D @hypequery/cli

Configure environment variables

Create a .env file in your project root with your ClickHouse credentials:

CLICKHOUSE_HOST=https://example.clickhouse.cloud:8443
CLICKHOUSE_DATABASE=default
CLICKHOUSE_USERNAME=cli_user
CLICKHOUSE_PASSWORD=super-secret

The CLI will read these variables when connecting to your database.

Generate schema types

Run the generate command to introspect your ClickHouse tables and create type-safe schema definitions:

npx @hypequery/cli generate --output analytics/schema.ts

npx hypequery generate --output analytics/schema.ts

This command:

• Reads your CLICKHOUSE_* environment variables
• Connects to your ClickHouse instance
• Introspects all tables and columns
• Writes TypeScript type definitions to analytics/schema.ts

Re-run this command anytime your database schema changes to keep types in sync.

Create the database client

Create analytics/client.ts to wire up the ClickHouse connection:

import 'dotenv/config';
import { createQueryBuilder } from '@hypequery/clickhouse';
import type { IntrospectedSchema } from './schema';

export const db = createQueryBuilder<IntrospectedSchema>({
  host: process.env.CLICKHOUSE_HOST!,
  database: process.env.CLICKHOUSE_DATABASE!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD,
});

This db instance is typed and ready to query your ClickHouse tables with full autocomplete and type safety.

Set up the query definitions

Create analytics/queries.ts with a placeholder Serve instance:

import { initServe } from '@hypequery/serve';
import { db } from './client';

const { define, queries, query } = initServe({
  context: () => ({ db }),
});

export const api = define({
  queries: queries({
    healthcheck: query
      .describe('Health check placeholder')
      .query(async () => ({ ok: true })),
  }),
});

You now have a fully typed API ready for queries. Replace the placeholder with your actual analytics endpoints.

(Optional) Configure framework integration

Next.js App Router

For Next.js projects, use the fetch adapter:

// app/api/analytics/route.ts
import { createFetchHandler } from '@hypequery/serve/adapters/fetch';
import { api } from '../../../analytics/queries';

const handler = createFetchHandler(api.handler);

export const GET = handler;
export const POST = handler;

Vite / SPA frameworks

Store hypequery files server-side. Browsers should call the generated HTTP endpoints, not ClickHouse directly. Use a proxy in your Vite config to forward /api/* requests to your hypequery server.

Other frameworks

See framework-specific setup guides:

• Vite setup guide
• Next.js setup guide
• Node.js setup guide