Scratch Org Definition File

The scratch org definition file is a blueprint for a scratch org. It mimics the shape of an org that you use in the development life cycle, such as sandbox, packaging, or production.

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—Licenses that can be added onto an edition, sometimes for an extra fee, such as multi-currency.
Org preferences—Org and feature settings used to configure Salesforce products, such as Chatter and Communities.

For example, you can turn Chatter on or off in a scratch org by setting the ChatterEnabled org preference in the configuration file. Setting up different configuration files allows you to easily create scratch orgs with different shapes for testing.

1{
2  "orgName": "Acme",
3  "country": "US",
4  "edition": "Enterprise",
5  "features": "MultiCurrency;AuthorApex",
6  "orgPreferences": {
7    "enabled": ["S1DesktopEnabled", "ChatterEnabled"],
8    "disabled": ["SelfSetPasswordInApi"]
9  }
10}

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
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
language	No	Default language for the country
features	No	None
orgPreferences	No	None

When indicating an orgName, don’t use a period as the last character. For example, Acme Corp. is not a good name because it causes an undesirable extra period in the scratch org username (scratchorg1497932510400@acmecorp..com).

Important

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 the different purposes or org shapes. 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.

Salesforce DX Developer Guide (Beta)

Scratch Org Definition File