Scratch Org definition file is getting used to create the shape of your scratch org. I would say it is the blueprint of your scratch org. You can use this definition file to create multiple scratch org from your repository.

Scratch org definitions come from JSON text files that are stored in your project’s repository and directory structure. When an SFDX project is first created, it comes with a config/project-scratch-def.json file that defines an extremely basic org “shape” for an empty scratch org.
That default scratch org likely looks nothing like your production org. You can use it for developing functionality that isn’t dependent on your org’s settings, or you can customize it using the settings that are available as part of the configuration file, or you can script your process to perform Metadata API deploys or other API actions to control settings that DX does not support yet.

Ideally, the combination of your DX source code (including all your programmatic and declarative customization) with your scratch org definition gets you close enough to Prod instance.

This definition file contains three main important information about your scratch org.

  • Which Edition? As of Winter’19, it supports Developer, Enterprise, Group or Professional
  • Add-on features: Functionalities you want to include while creating the scratch org like communities, StateAndCountryPicklist, LiveAgent etc.
  • Settings: Org and Feature settings used to configure Salesforce products, such as nameSettings, ideaSettings, caseSettings, omniChannelSettings.
Let’s dig into a Scratch Org definition file now –

{
    "orgName": "Sudipta Deb Company",
    "username": "sudipta-test-scratch@sudipta.com",
    "adminEmail": "sudipta.deb@gmail.com",
    "description": "This is the scratch org created by Sudipta Deb",
    "edition": "Enterprise",
    "features": ["Communities", "StateAndCountryPicklist", "LiveAgent"],
    "settings": {
        "orgPreferenceSettings": {
            "s1DesktopEnabled": true,
            "networksEnabled": true,
            "chatterEnabled": true
        },
        "nameSettings": {
            "enableMiddleName": true,
            "enableNameSuffix": true
        },
        "quoteSettings": {
            "enableQuote": true
        },
        "liveAgentSettings": {
            "enableLiveAgent": true
        },
        "omniChannelSettings": {
            "enableOmniChannel": true
        },
        "ideasSettings": {
            "enableIdeas": true
        },
        "caseSettings": {
            "emailToCase": true
        }
    }
}

Now let me explain different parts of this definition file –

  • orgName:  It is just giving a name of your organization in the scratch org. 
  • username: username of the scratch org user
  • adminEmail: Email address of the Dev Hub user making the scratch org creation request.
  • edition: provides the Salesforce edition of the scratch org.
  • description: Giving description of the scratch org. It’s a good practice to provide description.
  • features: In my example, I am enabling communities, StateAndCountryPicklist, LiveAgent in the scratch org.