Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Enable Dev Hub Features in Your Org
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Supported Scratch Org Editions and Allocations
Build Your Own Scratch Org Definition File
Create a Scratch Org Based on an Org Shape
Create Scratch Orgs
Select the Salesforce Release for a Scratch Org
Push Source to the Scratch Org
Pull Source from the Scratch Org to Your Project
Scratch Org Users
Manage Scratch Orgs from Dev Hub
Scratch Org Error Codes
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
First-Generation Managed Packages
Second-Generation Managed Packages
Partner Licensing Platform (Developer Preview)
Unlocked Packages
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 Orgs

The scratch org is a source-driven and disposable deployment of Salesforce code and metadata. A scratch org is fully configurable, allowing developers to emulate different Salesforce editions with different features and preferences. You can share the scratch org configuration file with other team members, so you all have the same basic org in which to do your development. In addition to code and metadata, developers can install packages and deploy synthetic or dummy data for testing. Scratch orgs should never contain personal data.

Scratch orgs drive developer productivity and collaboration during the development process, and facilitate automated testing and continuous integration. You can use the CLI or IDE to open your scratch org in a browser without logging in. Spin up a new scratch org when you want to:

  • Start a new project.
  • Start a new feature branch.
  • Test a new feature.
  • Start automated testing.
  • Perform development tasks directly in an org.
  • Start from “scratch” with a fresh new org.

Scratch Org Creation Methods

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

Before creating a scratch org, you must configure it so it has the features, settings, licenses, and limits that mirror a source org, often your production org. The combination of features, settings, edition, licenses, and limits are what we refer to as the org’s shape.

We offer these methods for configuring scratch orgs:

On Which Salesforce Instances Are Scratch Orgs Created?

Scratch orgs are created on sandbox instances. The sandbox instance depends on the country information used when creating the Dev Hub org.

Scratch orgs for Government Cloud and Public Cloud are created in the region where the Dev Hub org is physically located.

  • Scratch orgs created from a Dev Hub org in Government Cloud are created in a Government Cloud instance.
  • Scratch orgs created from a Dev Hub org in Public Cloud are created on a Public Cloud instance.

If you notice that your scratch orgs aren’t located in the expected region, create a Salesforce Support case.

Scratch Org Expiration Policy

A scratch org is temporary and is deleted along with the associated ActiveScratchOrgs records from the Dev Hub after their expiration. This expiration process ensures that teams frequently sync their changes with their version control system and are working with the most recent version of their project.

Scratch orgs have a maximum 30 days lifespan. You can select a duration from 1 through 30 days at the time of creation, with the default set at 7 days. After the scratch org has expired, you can’t restore it.

Deleting a scratch org doesn’t terminate your scratch org subscription. If your subscription is still active, you can create a new scratch org. Creating a new scratch org counts against your daily and active scratch org limits.

Note