Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Scratch Org Definition File
Scratch Org Definition Configuration Values
Create Scratch Orgs
Salesforce DX Project Structure and Source Format
Push Source to the Scratch Org
Assign a Permission Set
Ways to Add Data to Your Scratch Org
Pull Source from the Scratch Org to Your Project
Track Changes Between the Project and Scratch Org
Scratch Org Users
Manage Scratch Orgs from Dev Hub
Development
Build and Release Your App
First-Generation Managed Packages
Unlocked Packages (Generally Available) and Second-Generation Managed Packages (Beta)
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

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 settings and configuration options associated with a scratch org determine its shape, 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.
  • Settings—Org and feature settings used to configure Salesforce products, such as Chatter and Communities.
By default, scratch orgs are empty. They don’t contain much of the sample metadata that you get when you sign up for an org, such as a Developer Edition org, the traditional way. Some of the things not included in a scratch org are:
  • 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, add this option: 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. If you want to override this value, enter the two-character, upper-case ISO-3166 country code (Alpha-2 code). You can find a full list of these codes at several sites, such as: https://www.iso.org/obp/ui/#search. This value sets the locale of the scratch org.
username No test-unique_identifier@example.com
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. To override the language set by the Dev Hub locale, see Supported Languages for the codes to use in this field.
features No None
orgPreferences (to be deprecated in Spring ’19) No None
settings No None
<custom field API name> No None. Useful for Dev Ops use cases where you want to track extra information on the ScratchOrgInfo object. First, create the custom field, then reference it in the scratch org definition by its API name.
Here’s what the scratch org definition JSON file looks like:

Some features, such as Communities, can require a combination of a feature and a setting to work correctly for scratch orgs. This code snippet sets both the feature and associated setting.

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.

Create a Custom Field for ScratchOrgInfo

You can add more options to the scratch org definition to manage your Dev Ops process. To do so, create a custom field on the ScratchOrgInfo object. (ScratchOrgInfo tracks scratch org creation and deletion.)

If you’re making these changes directly in your production org, proceed with the appropriate levels of caution. The ScratchOrgInfo object is not available in sandboxes or scratch orgs.

Important

  1. In the Dev Hub org, create the custom field.
    1. From Setup, enter Object Manager in the Quick Find box, then select Object Manager.
    2. Click Scratch Org Info.
    3. In Fields & Relationships, click New.
    4. Define the custom field, then click Save.
  2. After you create the custom field, you can pass it a value in the scratch org definition file by referencing it with its API name.

    Let’s say you create two custom fields called workitem and release. Add the custom fields and associated values to the scratch org definition:

  3. Create the scratch org.