Configuration

Ploy uses a ploy.yaml file in the root of your repository to configure build settings and deployment options. This file provides fine-grained control over how your project is built and deployed.

Quick Start

Create a ploy.yaml file in your repository root:

kind: static
build: npm run build
out: dist

Commit and push the file to trigger a deployment with your custom configuration.

Configuration Options

kind

Type: "static" | "nextjs" Required: No (auto-detected if omitted)

Specifies the project type:

• static: Static site generation (React, Vue, Angular, HTML, etc.)
• nextjs: Next.js applications with server-side rendering support

kind: static

Example - Static React App:

kind: static
build: npm run build
out: dist

Example - Next.js App:

kind: nextjs
build: npm run build
out: .next

build

Type: string Required: Yes (when kind: static)

The command to run to build your project. This is typically a script defined in your package.json.

build: npm run build

Common examples:

# npm
build: npm run build

# pnpm
build: pnpm build

# yarn
build: yarn build

# Custom script
build: npm run build:production

out

Type: string Required: No (auto-detected if omitted) Default: Framework-specific (e.g., dist, build, .next)

The relative path to the output directory containing your built files.

out: dist

Validation rules:

• Must be a relative path (not absolute)
• Cannot start with /
• Cannot contain .. (path traversal prevention)
• Trailing slashes are automatically removed

Common output directories:

Example:

kind: static
build: npm run build
out: dist

base

Type: string Required: No Default: Repository root

The base directory where your project is located within the repository. This is useful for monorepos where your deployable project is in a subdirectory.

base: apps/web

Validation rules:

• Must be a relative path (not absolute)
• Cannot start with /
• Cannot contain .. (path traversal prevention)
• Trailing slashes are automatically removed

Monorepo example:

my-monorepo/
├── apps/
│   ├── web/          ← Your Next.js app
│   └── api/
├── packages/
│   └── ui/
└── ploy.yaml

kind: nextjs
base: apps/web
build: npm run build
out: .next

monorepo

Type: boolean Required: No Default: false

Enables monorepo mode. When enabled, Ploy will:

• Look for package.json in the repository root
• Install dependencies from the root
• Execute build commands from the base directory

monorepo: true
base: apps/web

Typical monorepo configuration:

kind: static
monorepo: true
base: apps/frontend
build: npm run build
out: dist

How it works:

1. Ploy installs dependencies from the repository root (where the main package.json is)
2. Changes directory to the base path
3. Runs the build command from the base directory
4. Looks for output in {base}/{out}

Complete Examples

Static Vite + React App

kind: static
build: npm run build
out: dist

Next.js App

kind: nextjs
build: pnpm build
out: .next

Monorepo with Turborepo

Project structure:

my-app/
├── apps/
│   ├── web/          # Next.js frontend
│   └── docs/         # Documentation site
├── packages/
│   └── ui/           # Shared UI components
├── package.json      # Root with workspaces
├── turbo.json
└── ploy.yaml

ploy.yaml for deploying the web app:

kind: nextjs
monorepo: true
base: apps/web
build: npm run build
out: .next

Custom Output Directory

kind: static
build: npm run build:prod
out: public/dist

SPA with Custom Base Path

kind: static
build: npm run build
out: build
base: packages/client

Configuration Priority

Ploy uses the following priority order for configuration:

1. ploy.yaml (highest priority) - Explicit configuration file
2. Dashboard settings - Manual overrides in project settings
3. Auto-detection (lowest priority) - Framework detection

Validation Errors

Common validation errors and how to fix them:

"Build command is required when kind is 'static'"

# ❌ Missing build command
kind: static
out: dist

# ✅ Fixed
kind: static
build: npm run build
out: dist

"Out path must be relative, not absolute"

# ❌ Absolute path
kind: static
build: npm run build
out: /dist

# ✅ Fixed - relative path
kind: static
build: npm run build
out: dist

"Out path cannot contain '..'"

# ❌ Path traversal
kind: static
build: npm run build
out: ../dist

# ✅ Fixed
kind: static
build: npm run build
out: dist

"Base path must be relative, not absolute"

# ❌ Absolute path
kind: static
base: /apps/web
build: npm run build

# ✅ Fixed
kind: static
base: apps/web
build: npm run build

Best Practices

1. Commit ploy.yaml to version control - Keep configuration in sync with code
2. Use kind: static for most frameworks - Only use nextjs for Next.js apps requiring SSR
3. Set monorepo: true for monorepos - Ensures proper dependency installation
4. Use relative paths - Never use absolute paths or .. for security
5. Match your framework's output directory - Check your framework's documentation for the correct out path

Troubleshooting

My build is failing

1. Check that your build command works locally: npm run build
2. Verify the out directory exists after building
3. Review deployment logs for specific error messages

My monorepo isn't building correctly

1. Ensure monorepo: true is set in ploy.yaml
2. Verify your root package.json has workspace configuration
3. Check that the base path points to the correct app directory
4. Ensure build commands are run from the base directory

Configuration changes aren't taking effect

1. Ensure ploy.yaml is committed to your repository
2. Push your changes to trigger a new deployment
3. Check deployment logs to see which configuration was used
4. Verify there are no YAML syntax errors in your file

Next Steps

• Review the Quick Start Guide for deployment basics
• Learn about Self-Hosting to deploy Ploy on your infrastructure
• Check out example projects for inspiration