What Is a Salesforce Scratch Org and When Custom Development Teams Should Use One

A Salesforce scratch org is a temporary Salesforce environment built for a specific development task. It starts clean, can be configured from project files, and is expected to be replaced rather than preserved. That makes it useful when a custom development team wants each developer, feature branch, test run, or package build to work in an isolated org with a known starting point.

The important part is the development model behind it. A scratch org works best when version control holds the source of truth and the org is created from that source. Salesforce describes scratch orgs as source-driven and disposable in its scratch org management guidance, and that wording explains why they behave differently from a long-lived sandbox. The org exists to support the work. The work shouldn’t depend on the org continuing to exist.

This distinction matters because many Salesforce teams already have sandboxes, deployment routines, test data, and admin habits built around persistent environments. This environment can improve isolation and repeatability, but it also exposes gaps in a team’s source control, setup automation, test data, and dependency management. Teams that treat it as a smaller sandbox often run into trouble. Teams that treat it as a reproducible build environment usually get more value from it.

This guide explains what a Salesforce scratch org is, how it works in Salesforce DX, how it differs from a sandbox or Developer Edition org, and when custom development teams should use one. It also covers setup, source tracking, CI, package work, org shape, snapshots, lifecycle limits, and the cases where a sandbox is still the better choice.

TL;DR

A Salesforce scratch org is a short-lived org created from a Dev Hub for development and automation. It starts without a copy of production metadata or production data, so teams must supply the metadata, permissions, packages, and test data the work needs. Salesforce’s Salesforce DX setup module describes scratch orgs as dedicated, configurable, short-term environments that fit feature work and automated testing, which is the right mental model for custom development teams.

Use a scratch org when the work benefits from a clean, repeatable environment that can be created from source and discarded after the task. Common cases include branch-based feature development, automated tests, pull request validation, package development, release-preview checks, and isolated experiments with supported settings. Keep sandboxes for work that depends on production-like metadata, larger volumes of realistic data, longer-lived testing, UAT, staging, training, or integrations that are difficult to reproduce in a disposable org.

·   Treat version control as the source of truth.

·   Keep the scratch org definition file with the project.

·   Automate permission assignment, package installation, and test-data loading.

·   Use source tracking for developer work unless a CI job has a reason to disable it.

·   Choose a sandbox when production resemblance matters more than fast recreation.

What Is a Salesforce Scratch Org?

A Salesforce scratch org is a configurable Salesforce environment that has a planned expiration date. It is created through Salesforce tooling and associated with a Dev Hub. The environment can be shaped for the work by choosing an edition and supplying supported features or settings. The result is a clean org that can be built again from project files instead of becoming a permanent development asset.

The current Salesforce CLI supports several creation paths. A team can create a scratch org from a definition file, specify an edition directly, create it from a snapshot, or create it from an org shape. Salesforce documents these options in the sf org create scratch command reference, which also shows that a Dev Hub is required and that source tracking is enabled by default. These options let teams choose between a minimal environment and one that starts closer to an established project state.

The scratch org definition file is central to the usual workflow. It acts as a blueprint for the org and can record the edition, supported features, settings, release choice, and other creation options. A custom development team can review that file like other project configuration. If a new feature needs Person Accounts, a specific platform setting, or another supported capability, that dependency should be declared instead of left as undocumented setup knowledge.

A scratch org also changes how developers think about ownership. A developer shouldn’t be the only person who knows how an org was prepared. The setup should be reproducible from the repository, scripts, and controlled test data. If the org expires or is deleted, the team should be able to create another environment and continue from committed source.

How Scratch Orgs Work in Salesforce DX

Salesforce DX is the broader development approach that connects source control, project structure, CLI commands, developer tooling, and repeatable environments. A scratch org fits this model because it can be created for a work item, populated from source, used for development or testing, and then deleted. The org is temporary while the repository stays permanent.

A typical Salesforce DX flow starts with a branch in version control. The developer creates an org, deploys the required metadata, assigns access, installs dependencies, loads sample records if needed, and runs the feature. Changes made in the org can be detected through source tracking and brought back into the project. The finished branch is reviewed and merged, while the org can be removed.

This flow works because source-driven development gives the repository a clear role: it defines what should exist in the environment. The scratch org definition file captures the environment requirements separately from the business metadata. Salesforce describes that file as the blueprint for a scratch org in its definition-file and org-shape guidance, and it can also be used when creating package versions. That gives custom development teams a versioned record of the conditions their code expects.

The Salesforce Dev Hub is the control point behind scratch org creation. It tracks requests and active scratch orgs, and its allocations affect how many environments a team can create or keep active. Teams with many developers or frequent CI jobs should plan around those limits instead of treating scratch org creation as unlimited infrastructure.

Salesforce Scratch Org vs Sandbox vs Developer Edition

The Salesforce scratch org vs sandbox question is really a question about what the environment needs to represent. A scratch org starts empty and is assembled for a task. A sandbox begins as a copy of production shape and metadata, with data availability depending on sandbox type. A Developer Edition org is a separate long-lived org that is useful for learning and experimentation but isn’t a copy of a customer production org.

Salesforce’s developer-environment comparison makes the practical split clear: scratch orgs suit source-tracked work and automated development flows, while Partial Copy and Full sandboxes are better when realistic production data or staging behavior matters. A scratch org has a maximum 30-day lifespan, while sandboxes support longer-running work and can be refreshed from production.

The Salesforce scratch org vs sandbox choice also changes by lifecycle stage. Salesforce’s own sandbox and scratch org explanation says scratch orgs are meant for source-driven development and expire, while sandboxes can remain available for longer periods. A custom development team can use both: scratch orgs for individual build work and CI, then sandboxes for integrated testing and business validation.

When Custom Development Teams Should Use a Scratch Org

A custom development team should use a scratch org when isolation and repeatability matter more than production resemblance. That usually happens when developers are working on separate features, when a pipeline needs a clean target, or when a package needs to be tested against a known configuration. The environment should be easy to rebuild and safe to discard.

Feature Branch Development

A feature branch is a strong fit because the environment can match the branch. The developer creates a clean org, deploys only the project source needed for that feature, develops the change, runs tests, and commits the result. Another developer can create a separate environment from another branch without sharing metadata state.

This reduces a common problem in shared sandboxes: unrelated work colliding because several developers change the same objects, permissions, flows, or Apex classes. Source-driven development also makes that isolation visible in the branch history, where the team can review what belongs to the feature before it is merged. The org boundary isolates the work, while Git remains the place where changes come together. The Salesforce DX scratch org model is especially useful when teams already use pull requests and branch policies.

Automated Validation

A scratch org works well when CI needs to prove that a branch can be deployed into a clean environment. The pipeline can create the org, deploy metadata with the Salesforce CLI project deploy command, run the required checks, and delete the org after the job. The result is a repeatable validation path that doesn’t depend on whatever happens to be present in a shared test org.

Package Development

Second-generation managed packages and package-based internal development also fit this environment model. Package teams need to know that dependencies are declared and that a package works when installed into a controlled org. A Salesforce scratch org provides a clean place to build or test package behavior without carrying unrelated metadata from a production copy.

Release Preview and Configuration Checks

During Salesforce release transitions, a team may need to test a feature against a preview or previous release option supported by the CLI. A disposable environment can be useful for focused compatibility checks. Teams should still validate the final integrated release in the environments required by their release process.

A Simple Readiness Test for Teams

A team is a good candidate for scratch-org development when a new developer can create a working environment from documented project inputs without copying an existing developer org. The test should include more than org creation. It should cover metadata deployment, required packages, permissions, safe test records, and any setup that the feature depends on. If one of those steps lives only in a person’s memory, the environment isn’t reproducible yet.

The same test helps decide how far to use scratch orgs. A team may be ready to use them for Apex and Lightning feature branches while still keeping a sandbox for integration work that needs vendor connections or a large metadata footprint. Adoption doesn’t have to replace every existing environment at once. Start with work that has clear boundaries and repeatable setup, then expand only when the build process proves dependable.

This gradual approach keeps the environment choice tied to the job. Source-driven development should reduce uncertainty in the build process. If creating a scratch org adds more manual setup than the feature itself, fix the setup path before making the org type a team-wide rule.

When a Scratch Org Is the Wrong Environment

A scratch org is a poor fit when the test depends on a large amount of production configuration or realistic business data that would be expensive to reconstruct. It is also a poor fit when the work needs to remain available for months, when business users need a stable UAT environment, or when external systems depend on fixed endpoints and long-lived credentials.

The Salesforce scratch org vs sandbox decision becomes easy when the test question is, “Does this work in conditions close to production?” If the answer requires the full metadata estate, a subset of copied production records, or a durable environment for several teams, a sandbox is usually the stronger choice. Salesforce’s Trailhead material on developer-environment guidance shows that scratch orgs don’t include production metadata or production data automatically, while developer sandboxes include production metadata.

A scratch org can also be the wrong choice for teams that haven’t made version control reliable. Source-driven development assumes that the repository contains the work that must survive the environment. If important changes still live only in orgs, a disposable environment creates risk because the org will expire. The same problem appears when setup depends on undocumented manual steps. Before moving daily work into scratch orgs, the team should be able to recreate the environment from files and scripts with little guesswork.

Long-running integration testing can be another mismatch. Some connected systems require allowlists, certificates, vendor-side setup, or stable user accounts. Repeating that setup for short-lived orgs may cost more time than the isolation saves. In those cases, a persistent integration sandbox can carry the durable external configuration while scratch orgs handle unit-level and feature-level work.

How to Set Up a Scratch Org Correctly

Good setup starts with the Salesforce Dev Hub, a Salesforce DX project, and a versioned scratch org definition file. The definition should represent what the project actually needs, not every feature available in a production org. A smaller declared shape is easier to understand and faster to troubleshoot when creation fails.

A basic creation command can look like this:

sf org create scratch \
  –definition-file config/project-scratch-def.json \
  –alias feature-orders \
  –duration-days 7 \
  –set-default

The CLI defaults the duration to 7 days, and Salesforce states that scratch orgs can live for up to 30 days. The `sf org create scratch` command also enables source tracking by default. Teams should choose a duration based on the work item instead of automatically asking for the longest possible life.

Configure the Org From Files

The scratch org definition file should hold creation settings that need to be repeatable. Project metadata should remain in the package directories, while setup scripts can handle operations that happen after creation. Keep these responsibilities separate so a developer can see which file controls org shape and which files contain the application itself.

Assign Access as Part of Setup

A clean org won’t automatically have every permission a feature needs. Permission sets should be deployed with the source and assigned as a repeatable step. Salesforce documents the CLI path for this in the permission-set assignment command, which supports assigning one or more permission sets to target users. This is better than asking developers to click through Setup each time.

Load Small, Purpose-Built Test Data

Keep test data limited to records that prove the feature works. Salesforce CLI can import structured JSON data with the data import tree command, including related records when the files are ordered correctly. A team can keep safe synthetic datasets in the repository and use them whenever a new environment is created.

How Source Tracking Changes the Development Workflow

Source tracking records differences between the local Salesforce project and a supported development org. In a scratch org, it is enabled by default unless the team disables it. That gives developers a clearer view of metadata changes made locally and in the org, including conflicts that need attention before source is moved in either direction.

The practical value is focus. Source-driven development is easier to sustain when the tooling can show what changed instead of forcing a developer to reconstruct a session from memory. A developer working on a flow, permission set, object, or Apex change doesn’t need to remember every file that changed during a session. The tooling can identify tracked changes, which makes source-driven development easier to maintain. Salesforce notes in the project deploy command documentation that scratch orgs support source tracking by default and that deployments can update tracking information.

Source tracking still needs discipline. It doesn’t replace code review, naming standards, dependency checks, or a clean Git history. A developer can still retrieve an unwanted change or overwrite work by resolving a conflict badly. The team should review diffs before committing and keep work items narrow enough that a pull request remains understandable.

There is also a good reason to disable scratch org source tracking in some CI jobs. Salesforce’s scratch-org CLI reference explains that tracking adds work such as conflict checks and file-system operations, and suggests disabling it when a pipeline only needs to deploy metadata and run tests. Developer environments and automated validation environments don’t need identical settings if their jobs are different.

How Scratch Orgs Fit CI, Testing, and Code Review

CI is one of the clearest uses for scratch orgs because the environment can be created from the same inputs on every run. A pipeline can authenticate to the Salesforce Dev Hub, request a new org, deploy the branch, assign access, load any required test fixtures, run checks, report the result, and remove the org. The pipeline tests the branch against a clean target rather than a shared environment with an unknown history.

Apex testing belongs in that flow. Salesforce’s Apex test CLI reference supports running selected classes, suites, individual tests, or broader test levels, with optional code-coverage output. Teams can use the same command locally and in CI so failures are easier to reproduce.

Static analysis can happen before or alongside org-based tests. Salesforce Code Analyzer is available through CLI and other developer surfaces, and Salesforce’s Code Analyzer setup guidance notes that the tool can be integrated into CI/CD. This helps a custom development team separate source-level checks from tests that need a live Salesforce runtime.

Scratch orgs can also support code review when a pull request needs a working demonstration. A reviewer can create an environment from the branch and reproduce the feature without borrowing the author’s org. That is useful for Lightning components, permission behavior, flows, package installs, and other changes that are easier to judge in a running org than from a diff alone.

Org Shape, Snapshots, and Complex Dependencies

A basic scratch org definition file is enough for many projects, but mature Salesforce estates often have more complicated dependencies. Org shape and snapshots can reduce the setup burden when teams need a closer match to an existing configuration or when repeated dependency installation takes too long.

Org shape records baseline characteristics from a source org, including features, limits, edition, and Metadata API settings. Salesforce’s org shape command reference explains that the resulting shape can be referenced through `sourceOrg` when a new scratch org is created. The shape doesn’t copy the source org’s business data or all of its metadata, so it should be seen as a configuration aid rather than a production clone.

A scratch org snapshot is different. It is a point-in-time copy of a scratch org that can be used as the basis for later scratch orgs. The Salesforce snapshot command reference describes how a snapshot is created from a source scratch org and then named in the creation configuration. This can help when repeated setup includes stable packages or prepared metadata that would otherwise take significant time on every build.

Custom development teams should add these tools only when the setup cost warrants them. A simple repository with a clear definition file and fast setup scripts is easier to maintain. Org shape or snapshots become useful when configuration complexity or package dependency time is a real bottleneck that the team has measured.

Packaging and Modular Salesforce Development

Scratch orgs are closely tied to modern Salesforce packaging because package work depends on known source and declared dependencies. A package should be buildable without relying on an old development org that contains hidden setup. A clean environment makes missing dependencies visible earlier.

Salesforce states in its package-development guidance that scratch orgs can be used to develop and test packages and can participate in CI steps that create package versions, install them, and run Apex tests. That pattern is useful even for internal custom development because it forces teams to define package boundaries and installation assumptions.

A Salesforce DX scratch org also helps when a large org is being split into clearer modules. A team can create an environment with only the packages and metadata needed for one area, then see whether the module really stands on its own. If the build fails because of undeclared cross-package references, the failure points to architecture work that a shared full-metadata sandbox might hide.

Packaging doesn’t mean every Salesforce implementation must become a set of packages. The useful principle is repeatable composition. Whether the team uses formal packages or package directories, the target state is a project that can create its required environment from controlled inputs and prove that those inputs are enough.

Limits, Lifespan, Costs, and Governance

A scratch org is disposable, but it still consumes platform allocations and team attention. The Salesforce Dev Hub controls scratch org creation, and the number of active or daily orgs available depends on the Dev Hub context. A team with heavy CI use should monitor failed jobs, abandoned orgs, and unnecessary creation because a wasteful pipeline can run into allocation limits during the workday.

Lifespan is another design constraint. Scratch orgs default to 7 days and can be created for a longer period up to the supported maximum of 30 days. They can’t serve as a durable record of unfinished work. Any code or metadata that matters should be committed before the org disappears, and test data that matters should be reproducible from safe source files or scripts.

Governance should also cover who can create orgs and how automation authenticates. Shared personal credentials are a bad foundation for CI. Teams should use the authentication pattern approved for their Salesforce environment and keep Dev Hub access limited to people and automation that need it. The scratch org itself may be temporary, but the ability to create environments and packages deserves normal access control.

There can also be feature-specific usage costs outside the basic scratch org concept. Some Salesforce products can consume metered resources even when used from a scratch environment. Teams working with paid platform services should check current product terms before running high-volume automated tests. A short-lived org doesn’t automatically mean the related service activity is free.

Conclusion

A scratch org works best as a disposable build environment created from source for a defined task. It gives custom development teams a clean way to isolate feature work, reproduce pull requests, run automated validation, test packages, and expose undeclared dependencies. The value comes from recreation, not from preserving the org.

The model also has clear limits. Scratch orgs start without a production copy, expire quickly, and can require setup work for packages, permissions, integrations, and test data. Teams that need realistic business data, durable UAT, staging, or long-running integration endpoints should keep sandboxes in the lifecycle. The strongest Salesforce delivery model often uses both environment types for different jobs.

A team is ready for a Salesforce scratch org when it can answer a simple question: if this org disappeared today, could we recreate the required environment from the repository and controlled setup steps? When the answer is yes, scratch orgs can make daily development and automated testing far more predictable.

FAQs

What Is a Salesforce Scratch Org in Simple Terms?

A Salesforce scratch org is a temporary Salesforce environment created for development or testing. It starts clean, is configured for a specific task, and expires after a set period. Teams normally create it from project files, use it for feature work or automation, then discard it after the work is saved in version control.

How Long Does a Salesforce Scratch Org Last?

The default lifespan is 7 days. Salesforce supports a maximum lifespan of 30 days for a scratch org. The duration is chosen when the org is created. Teams should treat the environment as temporary and keep important source outside the org.

Does a Scratch Org Copy Production Data?

No. A scratch org doesn’t automatically copy production data or production metadata. Teams deploy the metadata they need and load controlled test records separately. This clean starting point is useful for isolated development, but it also means production-like testing may require a sandbox instead.

What Is the Salesforce Dev Hub Used For?

The Salesforce Dev Hub is the org used to create and manage scratch orgs. It records scratch org activity and applies the allocations available to the organization. Development tools and CI jobs authenticate to the Dev Hub when they need to request a new scratch org.

What Is a Scratch Org Definition File?

A scratch org definition file is a JSON file that describes the org configuration needed for a project. It can specify the edition and supported settings or features. Keeping the file in version control helps teams create similar environments without relying on manual setup notes.

Is a Scratch Org Better Than a Sandbox?

Neither environment is better for every job. Scratch orgs fit isolated source-driven development, automated validation, and package work. Sandboxes fit longer-lived testing and scenarios that need production metadata or realistic data. Many Salesforce teams use both in the same delivery lifecycle.

Can Each Developer Have a Separate Scratch Org?

Yes. Separate scratch orgs are a common pattern for custom development teams because each developer can work without changing a shared development environment. The team’s Salesforce Dev Hub allocations still determine how many orgs can be active or created within the applicable limits.

Should CI Use Source Tracking in a Scratch Org?

Usually, CI doesn’t need source tracking if the job only deploys a known branch and runs tests. Salesforce allows source tracking to be disabled when a scratch org is created. Developer work often benefits from tracking because it helps detect local and org metadata changes.

Can a Scratch Org Be Used for UAT?

It can support a narrow review, but it is usually a poor choice for formal UAT that needs stable access, production-like metadata, realistic data, or a long test window. Partial Copy or Full sandboxes are normally a better fit for those conditions.

Can a Scratch Org Be Used for Apex Development?

Yes. Developers can deploy Apex classes and triggers to a scratch org, run tests, inspect failures, and commit the finished source back to version control. The environment is useful when the team wants isolated Apex work with a reproducible starting point.

Can Scratch Orgs Be Used for Lightning Web Components?

Yes. Lightning Web Components can be developed and tested in scratch orgs. The project source is deployed to the org, and developers can use Salesforce CLI and VS Code tooling during the development cycle. Required settings and permissions should be part of the repeatable setup.

What Is an Org Shape for Scratch Orgs?

Org shape captures baseline characteristics from a source org, such as edition, supported features, limits, and settings. A team can use that shape when creating a scratch org so it more closely reflects the source environment without copying all production metadata or business data.

What Is a Scratch Org Snapshot?

A scratch org snapshot is a point-in-time copy of a prepared scratch org. Teams can create later scratch orgs from that snapshot. It can reduce repeated setup when a project has stable packages or configuration that takes significant time to install or prepare.

Can Scratch Orgs Be Used for Package Development?

Yes. Scratch orgs are part of Salesforce’s package-development workflow for second-generation managed packages and are also useful for internal package-based development. Teams can build or install package versions in clean environments and run tests against declared dependencies.

What Happens When a Scratch Org Expires?

The environment becomes unavailable, so developers shouldn’t store unique work there. Source, configuration, setup scripts, and safe test fixtures should live outside the scratch org. If the project is prepared correctly, the team can create a new org and continue from version-controlled inputs.