Next.js

Ploy provides first-class support for Next.js applications with access to Cloudflare-compatible D1 and KV bindings, plus queues and workflows, through a simple integration package.

Installation

Install the Ploy CLI and Next.js integration:

pnpm add @meetploy/cli @meetploy/nextjs

Add a dev script to your package.json:

{
	"scripts": {
		"dev": "ploy dev"
	}
}

Configuration

Create a ploy.yaml file in your project root:

kind: dynamic
build: pnpm build
out: dist

Update your next.config.ts to initialize Ploy bindings in development:

import type { NextConfig } from "next";
import { initPloyForDev } from "@meetploy/nextjs";

if (process.env.NODE_ENV === "development") {
	await initPloyForDev();
}

const nextConfig: NextConfig = {
	output: "standalone",
};

export default nextConfig;

Usage

Use getPloyContext() to access Ploy bindings in Server Components or API routes:

import { NextResponse } from "next/server";
import { getPloyContext } from "@meetploy/nextjs";

export async function GET() {
	const { env } = getPloyContext();

	// Access your bindings through env
	const result = await env.DB.prepare("SELECT * FROM users").all();

	return NextResponse.json({ users: result.results });
}

Local Development

Run your Next.js app with Ploy:

pnpm dev

This starts:

• Your Next.js app
• The Ploy emulator for databases, queues, and workflows
• A local dashboard at http://localhost:4000 for insights

Environment Variables

Read them with process.env, exactly as in any Next.js app:

export default function Page() {
	return <p>{process.env.APP_NAME}</p>;
}

Values come from a .env file locally and from the Ploy dashboard in production. There is nothing to declare — ploy.yaml has no env section — and getPloyContext() is only needed for bindings such as databases and queues.

The same values are on env.vars if you prefer reading them from the context rather than a global.

See Environment Variables for the full details.

Type Safety

Generate TypeScript types from your ploy.yaml:

pnpm ploy types

This creates an env.d.ts file with type-safe bindings:

import type { Database, StateBinding } from "@meetploy/types";

declare module "@meetploy/nextjs" {
	interface PloyEnv {
		DB: Database;
		STATE: StateBinding;
	}
}

Now getPloyContext() returns properly typed bindings:

const { env } = getPloyContext();
// env.DB is typed as Database
// env.STATE is typed as StateBinding (Cloudflare KV-compatible)

Next Steps

• Database - Add SQLite databases to your app
• Queues - Process background jobs
• Workflows - Build durable multi-step processes
• Environment Variables - Configure your app with process.env