Org Skills

Packaging — unlocked, org-dependent, 2GP managed

Supporting material for salesforce-frontend-architecture. Agents load it on demand; it ships inside the skill folder.

RawSource

Target: Spring '26. Sources: Second-Generation Managed Packages, Unlocked Packages, sf package commands.

1. Choosing the package type

Type Namespace Source of truth Choose when The catch
Unlocked package Optional (usually none) Your git repo Internal org development, a shared design system, a domain module Admins can still change the metadata in the org; drift is caught by CI, not by the platform
Org-dependent unlocked package None Your git repo, but it compiles against one org The legacy org's metadata is tangled and the package genuinely cannot build in a clean scratch org No scratch-org validation, so the safety net you most need is the one you lose. Treat it as a migration step, not a destination
2GP managed package Required, permanent Your git repo, versioned and locked Distributing to other orgs: AppExchange, an ISV product, or your own multi-org estate The namespace prefixes every API name forever; upgrades follow managed-package rules; some metadata is not upgradeable
Unpackaged metadata — A directory Org-specific configuration that is not a reusable unit (page layouts, profiles, the org's own flexipages) No versioning and no dependency graph — keep it small and deliberate

Rule of thumb: one org → unlocked; many orgs or external customers → 2GP managed; neither → unpackaged. Org-dependent is the escape hatch with a deadline attached.

2. Dependency rules that keep a multi-package repo sane

// sfdx-project.json
{
  "packageDirectories": [
    { "path": "packages/design-system", "package": "org-design-system", "versionNumber": "2.4.0.NEXT", "default": false },
    { "path": "packages/sales-orders",  "package": "org-sales-orders",  "versionNumber": "1.9.0.NEXT", "default": true,
      "dependencies": [ { "package": "org-design-system", "versionNumber": "2.4.0.LATEST" } ] }
  ],
  "namespace": "",
  "sourceApiVersion": "66.0"
}
  • Dependencies point one way: feature packages depend on the design system, never the reverse. A circular dependency means the split is wrong.
  • Pin with .LATEST during development and to an exact version for a release build, so a promoted version is reproducible.
  • Every package has its own CI job: create a version, install it into a fresh scratch org with its dependencies, run its tests. A package that only builds in the big shared sandbox is not a package.
  • Metadata that cannot live in a package (profiles, most org settings) stays unpackaged and is applied by the pipeline — see salesforce-devops.

3. Versioning and promotion

sf package version create --package org-design-system --installation-key-bypass \
  --code-coverage --wait 60
sf package version promote --package "org-design-system@2.4.0-7"      # released, immutable
sf package install --package "org-design-system@2.4.0-7" --target-org staging --wait 20
  • Only a promoted version can be installed in production, and a promoted version is immutable — bump the patch instead of "just rebuilding".
  • Semantic meaning the org can rely on: major = breaking API change to an @api property or an exposed Apex method, minor = new components or properties, patch = fixes.
  • Keep a changelog per package next to the code, written for the admins and developers who install it, not for the committers.

4. Namespaces and the multi-org question

  • A namespace is permanent. mypkg__OrderList appears in every API name, every SOQL of a subscriber, every integration payload. Take one only when you genuinely distribute across orgs.
  • For an internal multi-org estate, weigh the namespace cost against the alternative: separate unlocked packages per org built from one repo, with the differences expressed as metadata rather than as forks.
  • Components in a managed package are only accessible outside it when marked global/@api — decide the public surface before the first release, because removing it later is a breaking change for every subscriber.
  • Managed-package components carry the lightningCommunity__RelaxedCSP consideration for Experience sites and cannot be edited in the subscriber org: the support model has to be part of the decision, not an afterthought.

5. Checklist

  • Package type chosen with its reason, and org-dependent has an end date
  • Dependency graph is acyclic and written in sfdx-project.json
  • Each package installs and passes its tests in a fresh scratch org in CI
  • Promotion is part of the release, and production installs only promoted versions
  • Public surface (@api, global) is deliberate and documented
  • Namespace taken only for genuine multi-org or AppExchange distribution
  • Changelog per package, written for installers