Salesforce DX Developer Guide

How Salesforce Developer Experience (DX) Tooling Changes the Way You Work
Provide Developers Access to Salesforce DX Tools
Project Setup
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Work with Data
Salesforce DX MCP Server and Tools (Beta)
Development
Build and Release Your App
Unlocked Packages
What’s an Unlocked Package?
Package-Based Development Model
Before You Create Unlocked Packages
Know Your Orgs
Create Org-Dependent Unlocked Packages
Workflow for Unlocked Packages
Configure Unlocked Packages
How We Handle Profile Settings in Unlocked Packages
Develop Unlocked Packages
Push a Package Upgrade for Unlocked Packages
Install an Unlocked Package
Migrate Deprecated Metadata from Unlocked Packages
Uninstall an Unlocked Package
Transfer an Unlocked Package to a Different Dev Hub
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Create Org-Dependent Unlocked Packages

Org-dependent unlocked packages are a variation of unlocked packages that allow you to create packages that depend on unpackaged metadata in the org where you plan to install the package (installation org).

User Permissions Needed
To create packages: Create and Update Second-Generation Packages

Untangling your production org metadata can be a daunting project. But now you have a solution that enables you to package metadata without completely accounting for all metadata dependencies: org-dependent unlocked packages. When you use org-dependent unlocked packages, metadata validation occurs during package installation, instead of during package version creation.

Longstanding and large production orgs often accumulate large amounts of metadata that are difficult to modularize when adopting a package-based Application Lifecycle Management (ALM) approach. Instead, you can package metadata that depends on unpackaged metadata in the installation org.

Org-dependent unlocked packages are a variation of unlocked packages, and not a separate package type. They follow the same package development steps, and use the same supported metadata types as unlocked packages.

Note

To create an org-dependent unlocked package, specify the orgdependent CLI parameter on the sf package create CLI command.
1sf package create -t Unlocked -r force-app -n MyPackage --org-dependent
Scenario Unlocked Packages Org Dependent Unlocked Packages
Build once, install anywhere Yes No. These packages are designed for specific production and sandbox orgs. You can install them only in orgs that contain the metadata that the package depends on.
Dependency validation Occurs during package version creation Occurs during package installation
Can depend on other packages Yes No
Requires dependencies to be resolved to create the package Yes No
Supported metadata types See the unlocked packaging channel of the Metadata Coverage Report. See the unlocked packaging channel of the Metadata Coverage Report.
Recommended development and testing environment Use scratch orgs to develop and test your unlocked packages. Use a sandbox that contains the dependent metadata. Consider enabling Source Tracking in Sandboxes to develop your org-dependent unlocked package. Then, test the package in a sandbox org before installing it in your production org.
Code coverage requirement Before you can promote and release an unlocked package, the Apex code must meet a minimum 75% code coverage requirement. We don’t calculate code coverage, but we recommend that you ensure the Apex code in your package is well tested.

To review which of your packages are org-dependent unlocked packages, use sf package list --verbose.