Package types

Every sfpm package has one packageType in its sfpm block. sfpm supports three types: unlocked, source, and data. Each type has its own build path and its own install path. Managed packages are not declared as a type. They come from managedDependencies, described below.

unlocked

An unlocked package is a Salesforce second-generation package. Its sfpm.packageType is unlocked, and it needs a Package2 container in the DevHub (packageId).

Two build modes exist, and the CLI choice decides which one runs:

• With --validation org or --validation full, sfpm asks the DevHub to create a package version. The artifact then carries a packageVersionId (04t).
• With --validation local, which is the CLI default, sfpm builds the package as source. No package version is created, and the artifact is labeled source. --source-only forces the same source build.

sfpm install installs the package version when the artifact has one. If it does not, sfpm source-deploys the package instead. sfpm deploy and sfpm deploy artifact always source-deploy unlocked packages. Installation keys for version installs are passed with --installation-key.

isOrgDependent marks an unlocked package as org-dependent. The staged sfdx-project.json entry for such a package omits its dependencies, and sfpm does not request asynchronous validation for it.

source

A source package holds metadata that sfpm deploys as-is. Its build stages the Salesforce source, analyzes Apex and fields, and writes the artifact metadata. It has no package version. Install and deploy always use a source deploy.

With org validation, sfpm deploys the package to a build org and runs its tests. The CLI supplies a build org with --build-org. If you use validation org or full and do not pass one, sfpm creates a scratch org for source packages. That requires a DevHub (--target-dev-hub).

Source packages can also be org-aliased with packageOptions.orgAliased. The package then has one subdirectory per target org alias, plus a required default/ directory. The mode option sets how the org directory combines with default/. union (the default) overlays the org directory on default/. disjoint uses only the org directory.

data

A data package holds reference data for SFDMU, the Salesforce Data Move Utility. The package folder must contain an export.json file that defines the objects to move. CSV files sit next to it.

The data build checks that export.json exists and parses, and that it lists at least one object. The data install runs an SFDMU import into the target org. Data packages do not have a skip check. sfpm imports them on every install or deploy.

The SFDMU builder and installer live in @b64hub/sfpm-sfdmu. The sfpm CLI loads that package, so data packages work with the CLI without extra setup.

Managed dependencies

Managed packages come from other publishers, such as an AppExchange package. You do not build them with sfpm. You list them in the package's top-level managedDependencies, as an alias and a subscriber package version ID (04t).

sfpm installs them as subscriber package versions during sfpm install and sfpm deploy artifact. sfpm build and sfpm deploy leave them out. Managed packages do not run lifecycle hooks.

Choosing a type

• Use unlocked when you want a versioned Salesforce package that other orgs install by version.
• Use source when the metadata should go to each org as-is, with no package version.
• Use data when the content is reference data that SFDMU should load.

Next

• Dependency graph: how packages are ordered.
• Deploy vs install: what each command sends to an org.