Scratch Org Definition Files vs Org Shape in Package Development

The scratch org definition file is used when you create scratch orgs, and also when you create new package versions. The scratch org definition file is a blueprint for your scratch org and defines the shape of the org you want for your package development work.

Build Your Own Scratch Definition File

If you read How Scratch Orgs Fit in the Package Development Workflow you might recall that the CLI command for creating scratch orgs includes a flag called --definition-file.

1sf org create scratch --target-dev-hub MyHub --definition-file config/project-scratch-def.json

In this example, project-scratch-def.json is the scratch org definition file. To learn more about what can be specified in this definition file, see Build Your Own Scratch Org Definition File in the Salesforce DX Developer Guide.

Similarly the CLI --definition-file flag can be used when creating a new package version.

1sf package version create --package "Expenser App"
2--definition-file config/project-scratch-def.json --code-coverage

When used in the package version create command, the scratch org definition file is used to specify the features, settings, or limits that your package requires.

When to Use Org Shape

If you’re developing managed packages to distribute on AgentExchange, we expect that you know what features and settings your packages depends on, and expect you to specify these requirements in a scratch org definition file. But there are scenarios like unlocked packages, or if you’re moving from 1GP to 2GP package development, where using Org Shape for Scratch Orgs can be useful.

During org shape creation, we capture the features, settings, edition, licenses, and limits of the specified source org. By using org shape you don’t have to manually list these items in the scratch org definition file.

The source org you use for org shape can’t be a sandbox or scratch org.

Note

Later when you create a package version, specify the org ID for the source org in the scratch org definition file.

1{
2  "orgName": "Acme",
3  "sourceOrg": "00DB1230400Ifx5"
4}

For more detailed instructions on enabling and creating org shape, review Create a Scratch Org Based on an Org Shape in the Salesforce DX Developer Guide.

If you’re moving from managed 1GP package development to 2GP package development, creating an org shape of your 1GP packaging org could be useful as you begin 2GP package development. Creating an org shape of your 1GP packaging org ensures that the features required for your package metadata are specified.

See Also