Multi Package Development

Multi-Package Development

This skill activates when a Salesforce project spans two or more packages (unlocked or managed) and the practitioner needs to design, build, install, or maintain the cross-package dependency graph. It covers package decomposition strategy, dependency DAG design, topological install ordering, sfdx-project.json multi-directory configuration, mono-repo vs. multi-repo layout, and CI/CD pipeline sequencing. It does not cover single-package creation, versioning, or 2GP ISV workflows.

Before Starting

Gather this context before working on anything in this domain:

• How many packages exist today, and what metadata does each contain? Review the packageDirectories array in sfdx-project.json and the packageAliases map.
• What is the current dependency graph? Each package directory's dependencies array declares subscriber package version IDs (04t...) it depends on. Circular dependencies are illegal and will cause version-create failures.
• Is the project in a mono-repo (all packages in one repository) or multi-repo (separate repos per package)? This drives CI/CD sequencing and source-of-truth decisions.
• Are packages unlocked, managed, or a mix? Managed packages introduce namespace isolation and @namespaceAccessible constraints that affect cross-package API surfaces.

Core Concepts

Dependency DAG (Directed Acyclic Graph)

Every multi-package project has a dependency graph. Salesforce enforces that this graph must be acyclic: if Package A depends on Package B, Package B cannot depend on Package A at any depth. The sf package version create command resolves dependencies at build time using the subscriber package version IDs listed in sfdx-project.json. If a dependency version does not exist or has not been promoted, the build fails.

The DAG determines:

• Build order — packages must be versioned from leaves (no dependencies) to root (depends on everything).
• Install order — packages must be installed in the same leaf-to-root order in every target org.
• Upgrade order — when updating packages, dependents must be upgraded after their dependencies.

Layered Package Architecture

The standard decomposition pattern is a layered model:

1. Base/Core layer — shared objects, fields, and platform utilities with no outbound dependencies.
2. Domain layer(s) — business-logic packages (Sales, Service, etc.) that depend on Base.
3. Experience/UI layer — LWC, Aura, Flows, and page layouts that depend on Domain and Base.

Each layer depends only on layers below it. This prevents circular references and keeps the base package stable.

sfdx-project.json Multi-Package Configuration

A single sfdx-project.json can declare multiple packages via the packageDirectories array. Each entry specifies:

• path — the source directory for that package's metadata.
• package — the package alias (must match a key in packageAliases).
• versionName / versionNumber — human-readable version label and MAJOR.MINOR.PATCH.BUILD format.
• dependencies — array of { "package": "<alias>", "versionNumber": "X.Y.Z.LATEST" } objects declaring upstream packages.
• default — at most one directory can be true; the CLI uses this when no --path is specified.

Only one entry should have "default": true. The packageAliases section maps human-readable names to subscriber package version IDs (04t...) or package IDs (0Ho...).

Install Ordering and Idempotency

Packages must be installed in topological order. Installing a package before its dependencies are present in the target org produces MISSING_DEPENDENCY errors. In CI/CD, this means the pipeline must:

1. Compute the topological sort of the DAG.
2. Install (or upgrade) each package in that order.
3. Handle partial failures gracefully — a failed mid-chain install should not leave the org in an inconsistent state.

The sf package install command is idempotent for the same version: re-installing an already-installed version is a no-op.

Common Patterns

Pattern 1: Layered Mono-Repo with Shared sfdx-project.json

When to use: Teams that own all packages and want a single source of truth for the dependency graph.

How it works:

my-project/
  sfdx-project.json
  force-app-base/     # Base package source
  force-app-sales/    # Sales domain package source
  force-app-service/  # Service domain package source
  force-app-ui/       # Experience layer source

{
  "packageDirectories": [
    {
      "path": "force-app-base",
      "default": true,
      "package": "MyOrg-Base",
      "versionName": "Spring 2025",
      "versionNumber": "1.2.0.NEXT",
      "dependencies": []
    },
    {
      "path": "force-app-sales",
      "package": "MyOrg-Sales",
      "versionName": "Spring 2025",
      "versionNumber": "1.1.0.NEXT",
      "dependencies": [
        { "package": "MyOrg-Base", "versionNumber": "1.2.0.LATEST" }
      ]
    },
    {
      "path": "force-app-ui",
      "package": "MyOrg-UI",
      "versionName": "Spring 2025",
      "versionNumber": "1.0.0.NEXT",
      "dependencies": [
        { "package": "MyOrg-Base", "versionNumber": "1.2.0.LATEST" },
        { "package": "MyOrg-Sales", "versionNumber": "1.1.0.LATEST" }
      ]
    }
  ],
  "packageAliases": {
    "MyOrg-Base": "0HoXXXXXXXXXXXXX",
    "MyOrg-Base@1.2.0-1": "04tXXXXXXXXXXXXX",
    "MyOrg-Sales": "0HoYYYYYYYYYYYYY",
    "MyOrg-Sales@1.1.0-1": "04tYYYYYYYYYYYYY",
    "MyOrg-UI": "0HoZZZZZZZZZZZZZ"
  }
}

Why not the alternative: Multi-repo setups require cross-repo version pinning and artifact passing between pipelines, adding significant coordination overhead. Mono-repo keeps the DAG visible in one file.

Pattern 2: Multi-Repo with Pinned Dependencies

When to use: Separate teams own separate packages and release on independent cadences, or packages span different Dev Hubs (e.g., ISV + customer).

How it works:

Each repo has its own sfdx-project.json with a single packageDirectories entry. Dependencies reference promoted subscriber package version IDs (04t...) directly:

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true,
      "package": "TeamB-Service",
      "versionNumber": "2.0.0.NEXT",
      "dependencies": [
        { "package": "TeamA-Base@1.5.0-3", "versionNumber": "1.5.0.LATEST" }
      ]
    }
  ],
  "packageAliases": {
    "TeamA-Base@1.5.0-3": "04tAAAAAAAAAAAAAAA",
    "TeamB-Service": "0HoBBBBBBBBBBBBB"
  }
}

A CI/CD "orchestrator" pipeline (in the consuming repo or a dedicated ops repo) runs after upstream packages publish new versions, updating the pinned 04t IDs and triggering downstream builds.

Why not the alternative: In a mono-repo, independent release cadences create merge conflicts in the shared sfdx-project.json and force all teams to coordinate releases.

Pattern 3: Unpackaged Metadata Alongside Packages

When to use: Some metadata (profiles, permission sets, org-wide settings) cannot be packaged or must be deployed org-specifically.

How it works:

Add an unpackaged directory to sfdx-project.json without a package key:

{
  "path": "force-app-unpackaged",
  "default": false
}

This directory is deployed via sf project deploy start after all packages are installed. It is not version-controlled by the packaging system.

Why not the alternative: Forcing unpackageable metadata into a package causes version-create failures or installs metadata that should vary per org (e.g., org-specific profiles).

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on multi-package architecture:

1. Map the current state — Parse sfdx-project.json and list all packageDirectories, their dependencies, and the packageAliases map. Draw the dependency DAG.
2. Validate the DAG — Confirm the graph is acyclic. Check that every dependency alias in dependencies arrays has a matching entry in packageAliases with a valid 04t or 0Ho ID.
3. Compute topological order — Determine the build and install order. Packages with no dependencies build first; packages that depend on them build next.
4. Apply layered decomposition — If restructuring, group metadata into Base (shared objects/fields), Domain (business logic), and Experience (UI) layers. Move metadata between packageDirectories paths accordingly.
5. Configure sfdx-project.json — Update packageDirectories, dependencies, and packageAliases to reflect the desired DAG. Ensure exactly one directory has "default": true.
6. Build and test in order — Run sf package version create for each package in topological order. Fix dependency resolution errors before proceeding to the next package.
7. Set up CI/CD sequencing — Configure the pipeline to build and install packages in topological order, passing 04t IDs from upstream stages to downstream stages.

Review Checklist

Run through these before marking work in this area complete:

• Dependency DAG is acyclic — no circular references between packages
• Every dependency alias in dependencies arrays resolves to a valid entry in packageAliases
• Exactly one packageDirectories entry has "default": true
• No metadata file appears in more than one package directory (no source duplication)
• Unpackageable metadata (profiles, org settings) is in a separate unpackaged directory, not in a package
• CI/CD pipeline builds and installs packages in topological order
• Each package's Apex tests pass independently (no cross-package test dependencies)

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Dependency version pinning with LATEST vs. explicit build — Using "versionNumber": "1.2.0.LATEST" in a dependency resolves to the latest build of that major.minor.patch at version-create time. If an upstream team creates a new build, your next version create silently picks it up. Pin to an explicit build number in production pipelines to avoid surprise regressions.
2. Package install order is not validated by the CLI — sf package install does not check whether dependencies are already installed before attempting installation. It simply fails with a MISSING_DEPENDENCY error. Your pipeline must enforce topological order.
3. Removing a component from a package requires deprecation — Once a component (field, object, class) is in a released package version, removing it from source and creating a new version causes an error. You must deprecate the component first or use --skip-ancestor-check (which breaks upgrade paths).

Output Artifacts

Related Skills

• unlocked-package-development — Single unlocked package creation, versioning, and installation; use alongside this skill when building individual packages within the multi-package graph
• second-generation-managed-packages — 2GP managed package ISV workflows; relevant when the multi-package architecture includes managed packages
• scratch-org-management — Scratch org configuration for multi-package development; scratch org definitions must include dependent package features
• github-actions-for-salesforce — CI/CD pipeline implementation; use when sequencing multi-package builds in GitHub Actions