Scratch Orgs and sfdx-project.json
By the end of this lesson, you'll be able to:
- Explain what a scratch org is and how it differs from a sandbox
- Identify the role of sfdx-project.json and a scratch org definition file
Prerequisites: Introduction to Salesforce DX
Scratch orgs vs. sandboxes
A scratch org is created instantly from your Dev Hub, entirely defined by a project-scratch-def.json file (edition, features, settings), and throwaway by design — it expires after a set number of days (7, by default). Your local source is pushed into it; it never holds the "real" copy of anything.
A sandbox, in contrast, is a longer-lived copy of production configuration (and optionally data) — closer to a staging environment than a disposable test bed.
sfdx-project.json
This file sits at the root of every SFDX project and declares packageDirectories (where your source lives on disk), the default sourceApiVersion, and Dev Hub-related settings. Every CLI command that pushes, pulls, or deploys source reads this file first to know what to operate on.
A minimal sfdx-project.json
{
"packageDirectories": [
{ "path": "force-app", "default": true }
],
"name": "quarry-dev-project",
"namespace": "",
"sfdcLoginUrl": "https://login.salesforce.com",
"sourceApiVersion": "60.0"
}packageDirectories tells the CLI where your metadata source lives on disk; sourceApiVersion pins which Salesforce API version new metadata is created against.
Exercise
Write the CLI command to create a new scratch org from a definition file named config/project-scratch-def.json, aliased as 'my-scratch'.
Show hint
sf org create scratch --definition-file <path> --alias <alias>
Scratch Orgs and sfdx-project.json — Quick Check
My Notes
Log in to keep private notes on this lesson.
Questions about this lesson
No questions yet — be the first to ask.
Log in to ask a question about this lesson.
Summary
A scratch org is a disposable, fully-configurable Salesforce org created on demand from a JSON definition file, and destroyed when you're done — sfdx-project.json ties your local source structure to the Dev Hub that creates them.