Documentation
Query the database
@ponder/client

@ponder/client

The @ponder/client package is a TypeScript client for querying a Ponder app with end-to-end type safety.

Example projects

These example apps demonstrate how to use @ponder/client.

Get started

Update to >=0.9.0

@ponder/client is available starting from version 0.9.0. Read the migration guide for more details.

Register client middleware

Register the client middleware to enable client queries.

src/api/index.ts
import { db } from "ponder:api";
import { Hono } from "hono";
import { client } from "ponder";
 
const app = new Hono();
 
app.use(client({ db }));
 
export default app;

Install @ponder/client

Install the @ponder/client package in your client project. This package works in any JavaScript environment, including the browser, server-side scripts, and both client and server code from web frameworks like Next.js.

shell
pnpm add @ponder/client

Create a client and send a request

Create a client using the root path of your Ponder server. For example, local development should use http://localhost:42069.

import { createClient } from "@ponder/client";
import * as schema from "../../ponder/ponder.schema";
 
const client = createClient("https://...", { schema });
 
const result = await client.db.select().from(schema.account).limit(10);

API reference

client.db

This method uses a readonly database role, with strict query limits. It provides a Drizzle query builder, similar to API functions.

import { createClient } from "@ponder/client";
import * as schema from "../../ponder/ponder.schema";
 
const client = createClient("https://...", { schema });
 
const result = await client.db.select().from(schema.account).limit(10);

client.live

Subscribe to live updates.

import { createClient } from "@ponder/client";
import * as schema from "../../ponder/ponder.schema";
 
const client = createClient("https://...", { schema });
 
const { unsubscribe } = client.live(
  (db) => db.select().from(schema.account),
  (result) => {
    // ...
  },
  (error) => {
    // ...
  }
);

Status

The status table contains information about the indexing status of each chain.

import { createClient, status } from "@ponder/client";
 
const client = createClient("https://...");
 
const mainnetStatus = client.db
  .select()
  .from(status)
  .where(eq(status.chainId, 1));

React

đź’ˇ

For an example of how to use @ponder/client with @tanstack/react-query for an automatically updating React hook, see the Next.js example.

@ponder/react

Coming soon.

API functionsGraphQL