Scratch Org Definition

The JSON file that spells out the edition, features, and settings a new scratch org should be created with.

Definition

A scratch org definition is the JSON file, conventionally config/project-scratch-def.json, passed to sf org create scratch --definition-file that explicitly declares what a new scratch org should look like: edition (Developer, Enterprise), enabled features (Communities, Multicurrency), org preferences, and settings that would otherwise require manual clicks in Setup. It's an explicit, version-controlled alternative to org shape, which instead captures configuration from an existing sandbox automatically. Teams commit their definition file to the repo so every developer's scratch org, and every CI-created one, starts from the same known configuration, which matters because a scratch org missing a feature the codebase depends on will fail deploys or tests in confusing ways. Getting the definition file wrong is one of the more common early scratch org headaches. Our guide to Salesforce DevOps platforms covers scratch org setup pitfalls in more detail.

In practice

How it works in Serpent

Serpent applies a team's scratch org definition automatically every time it provisions a scratch org as part of task setup, so every developer gets an identically configured environment without manually running CLI flags. Org preferences, features, and seed data all apply consistently across the pooled scratch orgs Serpent keeps warm for the team. See org management in Serpent for how scratch org provisioning fits alongside sandboxes.

Common questions