Salesforce DX Developer Guide
jNewer Version Available
Create Scratch Orgs
Before you create a scratch org:
- Set up your Salesforce DX project
- Authorize the Dev Hub org
- Create the scratch org definition file (build your own or use an org shape)
You can create scratch orgs for different functions, such as for feature development, for development of packages that contain a namespace, or for user acceptance testing.
Indicate the path to the scratch definition file relative to your current directory. For sample repos and new projects, this file is located in the config directory.
Ways to Create Scratch Orgs
You can override many of the options in the user definition file by specifying the corresponding flag at the command line when you run org create scratch. This technique allows multiple users or continuous integration jobs to share a base definition file and then customize options when they run the command. This example overrides the adminEmail and edition options.
You’re not required to specify a definition file when you create a scratch org, as long as you specify the required flag --edition.
This example creates a scratch org from a snapshot with the specified name.
This example creates a scratch org from an org shape with the specified ID.
Create a scratch org for user acceptance testing or to test installations of packages. In this case, you don’t want to create a scratch org with a namespace. You can use this command to override the namespace value in the scratch org definition file. This example also specifies the scratch org’s duration, which indicates when the scratch org expires (in 1-30 days). The default duration is 7 days.
Specify the Salesforce release for the scratch org. During the Salesforce release transition, you can specify the release (preview or previous) when creating a scratch org. See Select the Salesforce Release for a Scratch Org for details.
Request a scratch org, but don’t wait for it complete, by specifying the --async flag.
The command displays a job ID that you pass to the org resume scratch command. Use this command to also resume a scratch org creation that times out.
Create a scratch org with source tracking disabled.
View Scratch Org Creation Progress
While executing, the org create scratch command displays running information about the background processes. When the command completes, it displays two important pieces of information: the org ID and the username.
Open the Scratch Org
If you used the --alias flag to set an alias, you can use that value for --target-org.
Salesforce Release Transition Periods
Timing is everything during the Salesforce release transition period. During the transition period, you can intend to create a scratch org on the current release but find that the scratch org is unexpectedly created on the preview release. If the instance on which the scratch is created transitions to the preview release after the creation request is initiated, the scratch org is created on the preview version instead of the current version. During this transition period, there’s no way to know when the sandbox (CS) instance will be upgraded.
If you open the scratch org and it isn’t on the expected version, you have some options. See “How Release Transitions Can Affect the Scratch Org Version” in Select the Salesforce Release for a Scratch Org.
Troubleshooting Tips
If the create command runs into an error, it’s not always clear if the scratch org was created. Issue this command on your Dev Hub org to see if it returns the scratch org ID, which confirms the existence of a scratch org that was created today and owned by you:
Use this information to determine if the creation actually worked. For example, let’s say your name is Jane Doe, and you created an alias for your Dev Hub org called DevHub: