Salesforce DX Developer Guide
jNewer Version Available
Scratch Org Definition File
The shape of an org is determined by the collection of settings associated with it, including:
- Edition—The Salesforce edition of the scratch org, such as Developer, Enterprise, Group, or Professional.
- Add-on features—Functionality that is not included by default in an edition, such as multi-currency.
- Org preferences—Org and feature settings used to configure Salesforce products, such as Chatter and Communities.
- Custom objects, fields, indexes, tabs, and entity definitions
- Sample data
- Sample Chatter feeds
- Dashboards and reports
- Workflows
- Picklists
- Profiles and permission sets
- Apex classes, triggers, and pages
Setting up different scratch org definition files allows you to easily create scratch orgs with different shapes for testing. For example, you can turn Chatter on or off in a scratch org by setting the ChatterEnabled org preference in the definition file. If you want a scratch org with sample data and metadata like you’re used to, we have an option for that: hasSampleData.
Here are the options you can specify in the scratch org definition file:
| Name | Required? | Default If Not Specified |
|---|---|---|
| orgName | No | Company |
| country | No | Dev Hub's country. Scratch orgs are located in a data center based on the specified country. |
| username | No | test-unique_identifier@orgName.net |
| adminEmail | No | Email address of the Dev Hub user making the scratch org creation request |
| edition | Yes | None. Valid entries are Developer, Enterprise, Group, or Professional |
| description | No | None. 2000-character free-form text field. The description is a good way to document the scratch org’s purpose. You can view or edit the description in the Dev Hub. From App Launcher, select Scratch Org Info or Active Scratch Orgs, then click the scratch org number. |
| hasSampleData | No | Valid values are true and false. False is the default, which creates an org without sample data. |
| language | No | Default language for the country |
| features | No | None |
| orgPreferences | No | None |
1{
2 "orgName": "Acme",
3 "country": "US",
4 "edition": "Enterprise",
5 "description": "Work Item #12345: add picklist to widget",
6 "hasSampleData": "true",
7 "features": ["MultiCurrency", "AuthorApex"],
8 "orgPreferences": {
9 "enabled": ["S1DesktopEnabled", "ChatterEnabled"],
10 "disabled": ["IsNameSuffixEnabled"]
11 }
12}Some features, such as Communities, can require a combination of a feature and an orgPreferences parameter to work correctly for scratch orgs. This code snippet sets both the feature and org preference.
1"features": ["Communities"],
2 "orgPreferences": {
3 "enabled": ["NetworksEnabled"],
4 ...You indicate the path to the scratch org configuration file when you create a scratch org with the force:org:create CLI command. You can name this file whatever you like and locate it anywhere the CLI can access.
If you’re using a sample repo or creating a Salesforce DX project, the sample scratch org definition files are located in the config directory. You can create different configuration files for different org shapes or testing scenarios. For easy identification, name the file something descriptive, such as devEdition-scratch-def.json or packaging-org-scratch-def.json.
We recommend that you keep this file in your project and check it in to your version control system. For example, create a team version that you check in for all team members to use. Individual developers could also create their own local version that includes the scratch org definition parameters. Examples of these parameters include email and last name, which identify who is creating the scratch org.