Scratch Org Definition File and its Customization

Salesforce Scratch org is a ‘use and throw’ org that we can use for the development and deployment of the Salesforce code and metadata. If you want to know what Scratch Orgs really is, check out my article How to create Salesforce Scratch Org. If you know the Scratch Org, we can move ahead and look at the Scratch Org definition file.

We know that Scratch Orgs are totally empty when created. Unlike sandbox, scratch org does not copy metadata and data from Production. In order to configure the scratch org as per our need, we use the Definition file. It’s a JSON file that contains the whole structure of what this scratch org will be. Starting from what edition, what features, and what feature settings need to be enabled.

Scratch Org Definition File creation

When we create the Definition file, if we are using Salesforce CLI we can name this file whatever we want and locate it wherever we want(wherever Salesforce CLI can access it). In other cases, if we are using VS Code make sure that the scratch org definition file is located in the config folder and its name ends in scratch-def.json.

When you create a Project in VS code, it will create you a Definition File by default. Check this:

Scratch Org Definition file definition file location

You could make changes to this file and use it while creating Scratch Org. Press CTRL + SHIFT +P from your keyboard in VS code and click on SFDX: Create a Default Scratch Org, the next step is to select our Definition file.

Scratch Org Definition file use

You can have multiple definition files and select the one you want when asked while creating Scratch Org. Now we know how to create and how to use it, now let us look into what is actually inside the file and what changes we can make.

Definition Structure

Scratch Org Definition file structure
  • 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.

To see all the options we have for Features, we have this complete list here: Scratch Org Features. To see all the options we have for the setting, here’s the link: Scratch Org Settings

Now that we know almost all the necessary details on the definition file, we are good to go. Scratch Orgs will be used extensively in the future and it’s a good thing if you get familiar with Scratch Orgs. Till then, happy coding, and may the force be with you.