Quickstart

The Pylo Next.js SDK gives you type-safe data fetching and React Query hooks for Next.js applications — with zero hand-written GraphQL.

Authentication

For user authentication, set up the Auth SDK first. The Next.js SDK can also be used without auth (e.g., with API tokens).

Install

$pnpm add @pylo/nextjs @tanstack/react-query

Environment

.env.local

PYLO_API_KEY=your-api-token-here

Create an API token in Settings > API Tokens in your Pylo admin panel. See API Tokens for details.

1. Generate Types

Create a config file and run the codegen CLI to generate TypeScript types from your Pylo schema.

pylo.config.ts

import { defineConfig } from '@pylo/nextjs/codegen';

export default defineConfig({
apiKey: process.env.PYLO_API_KEY!,
folder: '.pylo', // optional, defaults to '.pylo'
});

$npx pylo generate

This creates a .pylo/ directory with your generated types and schema metadata:

.pylo/
  index.ts            # PyloSchema interface + type re-exports
  entities.ts         # Individual entity interfaces
  schema-metadata.ts  # Runtime metadata for the query builder

When to regenerate

Run npx pylo generate whenever you add, remove, or modify entities or fields in Pylo. Add it as a prebuild script for CI/CD.

2. Server Client

Create the typed server client for Server Components and Server Actions:

lib/pylo.ts

import { createPyloServer } from '@pylo/nextjs/server';
import type { PyloSchema } from '../.pylo';
import { schemaMetadata } from '../.pylo/schema-metadata';

export const pylo = createPyloServer<PyloSchema>({ schemaMetadata });

3. Client Hooks

Create the typed React Query hooks for Client Components:

lib/pylo-hooks.ts

import { createPyloHooks } from '@pylo/nextjs/hooks';
import type { PyloSchema } from '../.pylo';
import { schemaMetadata } from '../.pylo/schema-metadata';

export const pylo = createPyloHooks<PyloSchema>({ schemaMetadata });

React Query provider

Wrap your app with QueryClientProvider from @tanstack/react-query. See the React Query docs for setup.

4. API Route

Create the GraphQL proxy route that client hooks use for data fetching:

app/api/graphql/route.ts

1
2
3

import { createPyloApiRoute } from '@pylo/nextjs/api';

export const { POST } = createPyloApiRoute();

Setup is complete. Head to Querying Data to start fetching data.

Command Palette