Salesforce DX Developer Guide
jSummer '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)
Metadata Coverage
What’s a Package?
Comparison of 2GP and 1GP Managed Packages
Package IDs and Aliases
Workflow for Second-Generation Packages
Best Practices for Second-Generation Managed Packages
Frequently Used Packaging Operations
Uninstall a Package
Publishing Your App on AppExchange
Gaps Between First-Generation and Second-Generation Managed Packaging
Test and Respond to the New Order Save Behavior
Limitations for Salesforce DX
Newer Version Available
Second-Generation Managed Packages
Second-generation managed packaging (2GP) ushers in a new way for AppExchange partners
to develop, distribute, and manage their apps and metadata. You can use 2GP to organize your
source, build small modular packages, integrate with your version control system, and better
utilize your custom Apex code. With version control being the source of truth, there are no
packaging or patch orgs. You can execute all packaging operations via Salesforce CLI, or
automate them using scripts. Submit second-generation managed packages for security review, and
list them on AppExchange.
Use 2GP to create new managed packages. You can’t currently migrate a first-generation package to a second-generation package.
Second-generation managed packaging addresses the specific needs of AppExchange partners. If you’re a customer or system integrator and you don’t plan to distribute a package to multiple customers, unlocked packaging is the preferred tool. You can use unlocked packages to organize your existing metadata, package an app or extension, or package new metadata. See Unlocked 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. -
Comparison of 2GP and 1GP Managed Packages
If you are familiar with first-generation managed packages (1GP) and wonder how 2GP differs from 1GP, here are some key distinctions. -
Namespaces
A namespace is a 1–15 character alphanumeric identifier that distinguishes your package and its contents from other packages in your customer’s org. A namespace is assigned to a package at the time that it’s created, and can’t be changed. -
Package IDs and Aliases
When you create a package or package version, Salesforce CLI creates a package alias based on the package name, and stores that name in the packageAliases section of the sfdx-project.json file. When you run CLI commands or write scripts to automate packaging workflows, it’s often easier to reference the package alias, instead of the package ID or package version ID. -
Before You Create Second-Generation Managed Packages
When you use second-generation managed packaging, to be sure that you set it up correctly, verify the following. -
Workflow for Second-Generation Packages
You can create and install a second-generation managed package directly from the 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. -
Best Practices for Second-Generation Managed Packages
We suggest that you follow these best practices when working with second-generation managed packages. -
Frequently Used Packaging Operations
-
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 helpful if you need to push a change for a hot bug fix. -
Install a Package
Install second-generation managed packages using the CLI or the browser. You can install package versions in a scratch org, sandbox org, DE org, or production org. -
Uninstall a Package
You can uninstall a package from a subscriber org using Salesforce CLI or from the Setup UI. When you uninstall second-generation managed packages, all components in the package are deleted from the org. -
Publishing Your App on AppExchange
If you’ve published a 1GP managed package, you’ll notice the process for publishing a 2GP managed package is different. Once you link your Dev Hub org to the AppExchange publishing console, all your released 2GP package versions are visible in the publishing console. -
Gaps Between First-Generation and Second-Generation Managed Packaging
The following functionality is supported in first-generation managed packaging, and not yet supported in second-generation managed packaging. We’re working to address these feature gaps. -
Test and Respond to the New Order Save Behavior
If you’ve created any type of package that includes the Order object, the installed package may not work, and package upgrades or new package installations are blocked. Here’s why. The Order Save Behavior Release Update addresses an issue in which Salesforce didn't correctly evaluate custom application logic on records associated with the Order object.