Claude Code for Pkl Config Language — Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are writing configuration files with Pkl, Apple’s programmable, type-safe configuration language. Pkl provides schemas, validation, and code generation — you define your configuration structure with types and constraints, then generate JSON, YAML, or language-specific config classes. Claude Code can write configuration, but it generates raw JSON/YAML without type safety or validation.

What Claude Code Gets Wrong By Default

  1. Writes raw JSON or YAML. Claude creates config.json or config.yaml without validation. Pkl provides schemas that validate configuration at evaluation time — typos and invalid values are caught before deployment.

  2. Duplicates configuration across environments. Claude copies config files with small changes for dev/staging/prod. Pkl supports amending and extending — dev.pkl amends base.pkl overriding only environment-specific values.

  3. Uses template strings for dynamic values. Claude generates config with string interpolation in Python/Node scripts. Pkl has built-in expressions, conditionals, and string interpolation — configuration logic stays in the config language.

  4. Ignores code generation. Claude maintains TypeScript interfaces and config files separately. Pkl generates TypeScript, Kotlin, Swift, and Go types from the same schema — config types stay in sync with application code automatically.

The CLAUDE.md Configuration

# Pkl Configuration Project

## Configuration
- Language: Pkl (Apple's config language)
- Types: schemas with validation constraints
- Output: generates JSON, YAML, plist, properties
- Codegen: TypeScript, Kotlin, Swift, Go types

## Pkl Rules
- Schema: class with typed properties and constraints
- Amend: child configs amend parent with overrides
- Evaluate: pkl eval config.pkl -f json
- Codegen: pkl-gen-typescript for TS types
- Modules: import "path/to/module.pkl"
- Constraints: fixed, hidden, default values
- Templates: for repeated structure patterns

## Conventions
- Base config: base.pkl with all defaults
- Environment configs: dev.pkl, staging.pkl, prod.pkl amending base
- Schema: types.pkl for shared type definitions
- Generate: pkl eval -f json for runtime consumption
- Codegen: generate types for application code
- CI: pkl eval --check for config validation in CI
- Modules for reusable config patterns

Workflow Example

You want to create a type-safe application configuration with environment-specific overrides. Prompt Claude Code:

“Create a Pkl configuration for a web application with database, Redis, and API settings. Define the schema with types and constraints, create a base config with defaults, and create dev and production environment overrides. Generate JSON output for the app to consume.”

Claude Code should create a Config.pkl schema class with typed fields and constraints (e.g., port: UInt16(isBetween(1, 65535))), base.pkl with default values, dev.pkl amending base with local development values, prod.pkl amending base with production values, and show the pkl eval prod.pkl -f json command for generating JSON output.

Common Pitfalls

  1. Not validating configs in CI. Claude generates JSON from Pkl but does not validate in CI. Add pkl eval --check *.pkl to your CI pipeline to catch configuration errors before deployment.

  2. Forgetting to regenerate after schema changes. Claude modifies the Pkl schema but does not regenerate TypeScript types. Run pkl-gen-typescript after schema changes to keep application types in sync.

  3. Over-engineering configuration logic. Claude writes complex computation in Pkl files. Pkl supports programming features, but configuration should remain declarative. Move complex logic to application code and keep Pkl configs simple and readable.