Next.js

This guide assumes you already have:

a typed db client
an analytics/queries.ts file exporting api
at least one routed query

If not, start with Manual Installation or Quick Start.

We've simplified the serve API in v0.2. If you're looking for the older builder-first API, see Migrate from v0.1.x Serve API and v0.1.x Serve API.

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;

Execute queries locally in server code

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

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

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>;
}

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

Next.js

Next.js

Mount the handler in App Router

Execute queries locally in server code

Preview docs locally

On this page