Home / devops / packaging-dependency-graph
packaging-dependency-graph
Model and verify unlocked package dependencies, version pinning, and promotion. NOT for 1GP managed packages — use devops/multi-package-development.
Open the skill folder on GitHub
Packaging Dependency Graph
Unlocked package dependencies pin a package to a specific version of another. Without a graph, you can accidentally ship a service-core change that depends on an unreleased sales-core version, breaking prod deploy. This skill walks through extracting the dependency graph with the SF CLI, pinning versions explicitly in sfdx-project.json, and enforcing promotion order with a RELEASE.md checklist plus a fresh-scratch install validation step in CI. Correctly modeled dependencies prevent the most common 'works in staging, fails in prod' failure mode for multi-package monorepos.
Recommended Workflow
- Run
sf package version displaydependencies --package <packageVersionId>for each package version; assemble the graph. (There is nosf package dependenciestopic — dependencies are read off a package version, not a package.) - In sfdx-project.json, pin deps to
@version(e.g.,sales-core@1.4.0-2). - Promote packages bottom-up: base utils first, then dependents.
- Validate install order on a fresh scratch org before promoting to prod.
- Document the promotion order in a RELEASE.md checklist.
Key Considerations
- Unlocked packages support LATEST, but pinning to a specific version is safer.
- Circular dependencies are disallowed; refactor to extract a third package.
- Promotion is one-way in the same org; keep old versions available via install links.
- Deletion of a package version is not supported in some flavors.
Worked Examples (see references/examples.md)
- Pinned deps — 3 packages
- Fresh-scratch validation — Before prod release
Common Gotchas (see references/gotchas.md)
- LATEST rot — Dev bumped base package; dependent silently breaks in prod.
- Circular dep —
sf package version createfails with SSA_CYCLIC_DEP. - Promotion skip — Promoted service-core before sales-core; installer fails.
Top LLM Anti-Patterns (full list in references/llm-anti-patterns.md)
- Depending on @LATEST in prod
- No fresh-scratch install test
- Manual promotion order
Official Sources Used
- Salesforce DX Developer Guide — https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/
- Unlocked Packaging — https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_dev2gp.htm
- SF CLI — https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/
- DevOps Center — https://help.salesforce.com/s/articleView?id=sf.devops_center_overview.htm
- Scratch Org Snapshots — https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_scratch_orgs_snapshots.htm
- sfdx-hardis — https://sfdx-hardis.cloudity.com/