Mount the handler in App Router

Create app/api/analytics/[...path]/route.ts:

import { api } from '@/analytics/queries';
import { createFetchHandler } from '@hypequery/serve';

const handler = createFetchHandler(api.handler);

export const runtime = 'nodejs';
export const GET = handler;
export const POST = handler;
export const OPTIONS = handler;

createFetchHandler is exported from the root @hypequery/serve package, so you do not need to import from an adapter subpath.

Execute queries locally in server code

Use the same definition without HTTP in server components, actions, and jobs:

import { api } from '@/analytics/queries';

export const dynamic = 'force-dynamic';

export default async function Page() {
  const stats = await api.run('dailyStats', {
    input: {
      startDate: '2025-01-01T00:00:00Z',
      endDate: '2025-01-31T23:59:59Z',
    },
  });

  return <pre>{JSON.stringify(stats, null, 2)}</pre>;
}

Use force-dynamic on Server Components or pages that query ClickHouse during render. Without it, Next.js may try to prerender the page at build time and fail or time out when the database is unavailable.

Preview docs locally

npx hypequery dev analytics/queries.ts

With basePath: '/api/analytics', the preview server exposes:

• docs at http://localhost:4000/api/analytics/docs
• OpenAPI at http://localhost:4000/api/analytics/openapi.json