Next.js Quickstart

The Next.js SDK (@pylo/nextjs) gives you type-safe data access and React Query hooks without hand-written GraphQL.

Authentication

For user login, set up Authentication first. The SDK also works without user auth by using an API token.

Install

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

1. Generate types

Create an API token in Settings > API Tokens in the admin panel (see API Tokens) and put it in .env.local.

.env.local

PYLO_API_KEY=your-api-token-here

pylo.config.ts

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

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

pylo generate loads .env and .env.local before reading the config.

$pnpm exec pylo generate

This creates a .pylo/ directory:

.pylo/
  index.ts     # PyloSchema interface + type re-exports
  entities.ts  # Individual entity interfaces

When to regenerate

Rerun pylo generate after changing entities or fields in Pylo. Add it as a prebuild script for CI.

2. Server client

For Server Components and Server Actions:

lib/pylo.ts

import { createPyloServer } from '@pylo/nextjs/server';
import type { PyloSchema } from '../.pylo';

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

3. Client hooks

For Client Components:

lib/pylo-hooks.ts

import { createPyloHooks } from '@pylo/nextjs/hooks';
import type { PyloSchema } from '../.pylo';

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

React Query provider

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

4. API route

The GraphQL proxy route the client hooks call:

app/api/graphql/route.ts

1
2
3

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

export const { POST } = createPyloApiRoute();

Querying

Command Palette