Salesforce DX Developer Guide
jNewer Version Available
Select the Salesforce Release for a Scratch Org
What Is Salesforce Preview?
During every major Salesforce release, you can get early access to the upcoming release in your scratch orgs and sandboxes to test new customizations and features before your production org is upgraded. This window is called the Salesforce Preview, and scratch orgs created on the upcoming release are called preview scratch orgs.
Normally, you create scratch orgs that are the same version as the Dev Hub. However, during the major Salesforce release transition that happens three times a year, you can select the Salesforce release version, Preview, or Previous, based on the version of your Dev Hub.
To try out new features in an upcoming release, you no longer have to create a trial Dev Hub on the upcoming version to create preview scratch orgs. You can use your existing Dev Hub that includes your existing scratch org active and daily limits.
For example, you can select a version over the next three releases during these release transition dates. Preview start date is when sandbox instances are upgraded. Preview end date is when all instances are on the GA release.
| Release Version | Preview Start Date | Preview End Date |
|---|---|---|
| Summer ’23 | May 7, 2023 | June 10, 2023 |
| Winter ’24 | September 10, 2023 | October 14, 2023 |
| Spring ’24 | January 7, 2024 | February 10, 2024 |
Because previous and preview are relative terms, your Dev Hub org version during the release transition determines their relative significance. Here’s what happens when you try to create a scratch org with one of the release values.
| Dev Hub Version | Preview | Previous |
|---|---|---|
| Dev Hub has upgraded to the latest version | Error (Dev Hub is already on the latest version) | Prior Dev Hub version |
| Dev Hub is still on the GA version | Version following the Dev Hub version (newly released Salesforce version) | Error (Dev Hub is on the GA version; previous version unavailable) |
Create a Scratch Org for a Specific Release
You can specify the release version in the scratch org definition file or directly on the command line. Any option you issue on the command line overrides what you have defined in your scratch definition file.
- Find out which instance your Dev Hub org is on: https://status.salesforce.com.
- Add the release option (lowercase) to your scratch org definition file.
Alternatively, you can specify the release value directly on the command line. Any values you specify on the command line override the values in the scratch org definition.
- Create the scratch org.
In this example, we’re creating a scratch org on the preview release.
Be sure to set the apiVersion to match the scratch org version.
To set it globally for all DX projects:
To set it on the command line:
What If I Want to Create a Pre-Release Scratch Org?
Pre-release is a very early build of the latest version of Salesforce that’s available before Salesforce Preview. It's not built to handle scale and doesn't come with any Salesforce Support service-level agreements (SLAs). For this reason, the only way to create a pre-release scratch org is to sign up for a pre-release trial Dev Hub org (subject to availability).