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
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
# Packaging — unlocked, org-dependent, 2GP managed
Target: Spring '26. Sources: [Second-Generation Managed Packages](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_dev2gp.htm), [Unlocked Packages](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_intro.htm), [`sf package` commands](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_package_commands_unified.htm).
## 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
```jsonc
// 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
```bash
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