Building a package with the modern Package Manager tooling follows a standard sequence from Dev Hub setup through version release. The walkthrough below covers a typical unlocked package scenario where an enterprise wants to distribute an internal app across multiple business unit orgs.
- Enable Dev Hub and set up the project
In the org that will serve as Dev Hub (typically the production org for ISVs or a dedicated admin org for enterprises), enable Dev Hub in Setup. Authorize the Dev Hub from the local Salesforce DX CLI (sf org login web). Initialize the project structure (sf project generate) with the appropriate packageDirectories. Add the package's source files to the right directory. Commit everything to source control before proceeding.
- Define the package and create the first version
Run sf package create to declare a new package in the Dev Hub, specifying the name, description, and type (managed or unlocked). Update sfdx-project.json with the package details and dependencies. Run sf package version create to build the first version. The command pushes source to a build scratch org, validates the package, and produces a 04t Id and install URL. Test the install URL in a clean scratch org to confirm the package installs correctly and behaves as expected.
- Test in sandboxes and iterate
Install the package version in one or more sandboxes representing the target subscriber environments. Run the standard testing for the application: unit tests, integration tests, user acceptance scenarios. Capture any issues, fix them in the source, and create new package versions iteratively. Each version is immutable once promoted, so most teams use unreleased versions during development and promote only the final candidates.
- Promote and distribute
Once a version passes all testing, run sf package version promote to mark it as released. Distribute the install URL to the subscriber orgs' admins, or have the central team run sf package install against each target org. Document the version in the org's package registry with the release date, what changed, and any subscriber-org configuration required. Schedule the subsequent version on a predictable cadence so subscribers know when to expect updates.
Required to anchor all package definitions and authorize the CLI for package operations.
The local project with packageDirectories, sfdx-project.json, and source files organized by package.
The command-line tool that runs all Package Manager operations.
Required on the Dev Hub for the user running package commands.
Required for tracking the package source over time. Git is the standard, with releases tagged to specific commits.
- Released package versions are immutable. If a released version has a bug, the fix is a new version, not an edit of the existing one.
- Dev Hub orgs cannot be sandboxes (with some exceptions). The Dev Hub is typically a production-class org.
- Managed package namespaces are permanent. Pick the namespace carefully because changing it requires creating a new package and migrating subscribers.
- Unlocked packages have weaker upgrade guarantees than managed packages. The subscriber org can edit unlocked package metadata, which can complicate later upgrades.
- First-generation packages and second-generation packages have different command surfaces. Mixing them is possible but requires careful tooling.