Next.js

Ploy provides first-class support for Next.js applications with access to databases, 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:

package.json

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

Configuration

Create a ploy.yaml file in your project root:

ploy.yaml

kind: dynamic
build: pnpm build
out: dist

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

next.config.ts

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;

The initPloyForDev() function reads your ploy.yaml and sets up mock bindings that proxy to the local Ploy emulator.

Usage

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

app/api/example/route.ts

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

The local dashboard lets you inspect database contents, view queue messages, and monitor workflow executions.

Type Safety

Generate TypeScript types from your ploy.yaml:

pnpm ploy types

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

env.d.ts

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

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

Now getPloyContext() returns properly typed bindings:

const { env } = getPloyContext();
// env.DB is typed as Database

Next Steps

Database - Add SQLite databases to your app
Queues - Process background jobs
Workflows - Build durable multi-step processes

Next.js

Next.js

Installation

Configuration

Usage

Local Development

Type Safety

Next Steps

On this page