Salesforce DX Developer Guide
Summer '26 (API version 67.0)
Spring '26 (API version 66.0)
Winter '26 (API version 65.0)
Summer '25 (API version 64.0)
Spring '25 (API version 63.0)
Winter '25 (API version 62.0)
Summer '24 (API version 61.0)
Spring '24 (API version 60.0)
Winter '24 (API version 59.0)
Summer '23 (API version 58.0)
Spring '23 (API version 57.0)
Winter '23 (API version 56.0)
Summer '22 (API version 55.0)
Spring '22 (API version 54.0)
Winter '22 (API version 53.0)
Summer '21 (API version 52.0)
Spring '21 (API version 51.0)
Winter '21 (API version 50.0)
Summer '20 (API version 49.0)
Spring '20 (API version 48.0)
Winter '20 (API version 47.0)
Summer '19 (API version 46.0)
Spring '19 (API version 45.0)
Winter '19 (API version 44.0)
Summer '18 (API version 43.0)
Spring '18 (API version 42.0)
Winter '18 (API version 41.0)
Summer '17 (API version 40.0)
Release Notes
Metadata Coverage
What’s a Package
Package-Based Development Model
Before You Create Unlocked Packages
Know Your Orgs
Create Org-Dependent Unlocked Packages
Workflow for Unlocked Packages
How We Handle Profile Settings in Unlocked Packages
Push a Package Upgrade
Migrate Deprecated Metadata from Unlocked Packages
Uninstall a Package
Limitations for Salesforce DX
Newer Version Available
Unlocked Packages
Salesforce offers different types of packages, and unlocked packages are especially
suited for internal business apps. Unless you plan to distribute an app on AppExchange, an
unlocked package is the right package type for most use cases. You can use unlocked packages to
organize your existing metadata, package an app, extend an app that you’ve purchased from
AppExchange, or package new metadata.
Unlocked packages follow a source-driven development model. The source of truth of the metadata contained in the package is your version control system, not what’s in an org. This model brings with it all the benefits of modern source-driven development models.
If you’re an AppExchange partner that plans to distribute your app to customers via AppExchange, second-generation managed packaging is the preferred tool. See Second-Generation Managed Packages for more information.
Note
-
What’s a Package
If you’re new to packaging, you can think about a package as a container that you fill with metadata. It contains a set of related features, customizations, and schema. You use packages to move metadata from one Salesforce org to another. -
Package-Based Development Model
To demonstrate the power of unlocked packages, here’s how packaging works in the traditional development model. For most production orgs, metadata traditionally is contained in two buckets: a set of managed packages installed from AppExchange, and unpackaged metadata. -
Before You Create Unlocked Packages
When you use unlocked packaging, to be sure that you set it up correctly, verify the following. -
Know Your Orgs
Some of the orgs that you use with unlocked packaging have a unique purpose. -
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). -
Workflow for Unlocked Packages
You can create and install an unlocked package directly from the Salesforce command line. -
Configure Packages
You include an entry in the sfdx-project.json file for each package to specify its alias, version details, dependencies, features, and org settings. From the command line, you can also set or change options, such as specifying an installation key, update the package name, or add a description. -
How We Handle Profile Settings in Unlocked Packages
When you package a profile in an unlocked or second-generation managed package, the build system inspects the contents of the profile during package creation and preserves only the profile settings that are directly related to the metadata in the package. The profile itself, and any profile settings unrelated to the package’s metadata are discarded from the package. -
Create a Package
A package is a top-level container that holds important details about the app or package: the package name, description, and associated namespace. -
Push a Package Upgrade
Push upgrades enable you to upgrade packages installed in subscriber orgs, without asking customers to install the upgrade themselves. You can choose which orgs receive a push upgrade, what version the package is upgraded to, and when you want the upgrade to occur. Push upgrades are particularly helpful If you need to push a change for a hot bug fix. -
Install a Package
Install unlocked packages using the CLI or the browser. You can install package versions in a scratch org, sandbox org, DE org, or production org. -
Migrate Deprecated Metadata from Unlocked Packages
You can deprecate metadata in an unlocked package, move that metadata to a new package, and then install the new package in your production org. -
Uninstall a Package
You can uninstall a package from an org using Salesforce CLI or from the Setup UI. When you uninstall unlocked packages, all components in the package are deleted from the org. -
Transfer an Unlocked Package to a Different Dev Hub
You can transfer the ownership of an unlocked package from one Dev Hub org to another.