Environment Variables

Environment variables are not declared anywhere. Every variable you set in the Ploy dashboard is available to your build and to your worker at runtime under env.vars, and during local development the same applies to every entry of your project's .env file.

Accessing Variables

All variables are available under env.vars in your worker:

export default {
	async fetch(request, env) {
		return Response.json({
			appName: env.vars.APP_NAME,
			apiUrl: env.vars.API_URL,
		});
	},
} satisfies Ploy;

In a Next.js app you keep using process.env as usual — Ploy's Next.js adapter injects the variables for you:

export async function GET() {
	return Response.json({ apiUrl: process.env.API_URL });
}

ploy types generates a vars property typed as Record<string, string>. Because variables are never declared, the CLI cannot know their names:

declare global {
	interface PloyEnv {
		vars: Record<string, string>;
	}
}

Local Development with .env

Create a .env file in your project directory:

APP_NAME=my-app
SECRET_KEY=my-local-secret
API_URL=http://localhost:3000/api

When you run ploy dev, every entry of that file is loaded and exposed under env.vars.

Production: Dashboard Variables

In production, env.vars is populated from the environment variables set on your project. The same values are also exported into the build environment, so they are available to next build and any other build step.

Setting Variables in the Dashboard

1. Go to your project settings in the Ploy dashboard
2. Navigate to the Environment Variables section
3. Add the variables your project needs

Variables can be added one at a time, or pasted in bulk in KEY=value form — for example straight from your local .env file.

Secret vs Plaintext

When adding variables in the dashboard, you can choose between:

• Secret: The value is encrypted and never displayed after creation. Use for API keys, tokens, and passwords.
• Plaintext: The value is stored and displayed in plain text. Use for non-sensitive configuration.

Variables Ploy Sets For You

Ploy injects a few variables of its own into every deployment:

Full Example

Project Structure

my-worker/
├── .env              # Local values (gitignored)
├── ploy.yaml         # Project configuration
├── env.d.ts          # Generated types
├── package.json
├── tsconfig.json
└── src/
    └── index.ts

ploy.yaml

kind: dynamic
build: pnpm build
out: dist

.env

APP_NAME=my-app
SECRET_KEY=dev-secret-key-123
API_URL=https://api.dev.example.com

src/index.ts

export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (url.pathname === "/config") {
			return Response.json({
				appName: env.vars.APP_NAME,
				apiUrl: env.vars.API_URL,
				// Never expose secrets in responses!
			});
		}

		// Use SECRET_KEY for authentication
		const authHeader = request.headers.get("Authorization");
		if (authHeader !== `Bearer ${env.vars.SECRET_KEY}`) {
			return new Response("Unauthorized", { status: 401 });
		}

		return Response.json({ message: "Authenticated" });
	},
} satisfies Ploy;

Next Steps

• Workers - Learn about Ploy workers
• Configuration - Full ploy.yaml reference
• Databases - Add persistent SQLite databases