Using scratch orgs requires the Salesforce CLI, a project in SFDX project format, an authorized Dev Hub, and a scratch org definition file. The first-time setup takes a few hours; daily use is fast once the toolchain is in place. The shift from org-driven to source-driven development is the bigger lift than the technical setup itself.
- Install the Salesforce CLI and VS Code Extensions
Install the sf CLI from developer.salesforce.com. Install VS Code with the Salesforce Extensions Pack. Run sf to confirm the install. The CLI authenticates against Dev Hubs and individual orgs through its login commands.
- Enable Dev Hub on the source org
Setup > Dev Hub > Enable Dev Hub. This authorizes the org to provision scratch orgs. Production is the standard Dev Hub for established teams; a dedicated free Developer Edition org works for solo developers.
- Authenticate the CLI to the Dev Hub
sf org login web --set-default-dev-hub. A browser opens for OAuth login. After successful authentication, the CLI remembers the Dev Hub for future scratch org creation.
- Create or open an SFDX project
sf project generate creates a new SFDX project structure. Open an existing one with sfdx-project.json at the root. The project must be in SFDX format (not the older metadata format) for scratch org workflows.
- Configure the scratch org definition file
Edit config/project-scratch-def.json. Specify edition, features, and settings. The CLI generates a sensible default; customize as needed for the project. Save the file in source control so the whole team uses the same scratch org shape.
- Create the scratch org
sf org create scratch --definition-file config/project-scratch-def.json --alias my-scratch --duration-days 7. The org provisions in 30-90 seconds. The CLI returns the login URL and credentials.
- Push source and seed data
sf project deploy start deploys the project source to the scratch org. sf data import tree --plan data/sample-plan.json seeds realistic test data. Both should run as part of an org-setup script for repeatable provisioning.
- Develop, test, and tear down
Edit metadata in the org or in source. Run tests with sf apex run test. Commit changes to source control before the org expires. Tear down with sf org delete scratch --target-org my-scratch when finished.
JSON config specifying edition, features, settings. Drives what the scratch org looks like.
How long the org lives before automatic deletion. Plan based on the work; default is 7.
Each Dev Hub has a limit on active and daily scratch orgs. Plan the allocation across the team.
- Scratch orgs are deleted at expiration, irreversibly. Commit all work to source control before the org disappears; the CLI does not warn about uncommitted changes.
- Scratch orgs start empty. Test code that assumes existing Accounts, Contacts, or other records will fail without data seeding. Build the seed step into the org creation script.
- Dev Hub allocations cap concurrent scratch orgs. Hitting the cap blocks new org creation; coordinate across the team or upgrade the Dev Hub tier for higher limits.
- Some features are not available in scratch orgs because they require licensed configuration. Confirm the definition file enables every feature the test code expects.
- Source tracking conflicts can arise when both source and the org change between push and pull. The CLI surfaces conflicts; resolve them through git diff and explicit pull/push decisions.