Creating a package

All packages start out as directory in your repo!

A package is a collection of metadata grouped together in a directory, and defined by an entry in your sfdx-project.json (Project Manifest).

// A sample sfdx-project.json with a package
{
  "packageDirectories": [
    {
      "path": "src/my-package",
      "package": "my-package",
      "versionNumber": "1.0.0.NEXT"
    }
  ]
}

Each package in sfp must have the following attributes as the minimum:

Attribute	Required	Description
path	yes	Path to the directory that contains the contents of the package
package	yes	The name of the package
versionNumber	yes	The version number of the package

sfp will not consider any entries in your sfdx-project.json for its operations if it is missing 'package' or 'versionNumber' attribute.

Package Types

By default, sfp treats all entries in sfdx-project.json as Source Packages. You can create different types of packages depending on your needs:

Package Type	Description
Source Package	Default package type for deploying metadata
Unlocked Package	Versioned, upgradeable package
Data Package	Package for data migration
Diff Package	Package containing only changed components

An unlocked package can additionally be created as org-dependent. That is a property of an unlocked package, not a package type of its own.

Creating Packages

The sfp package create commands write the package entry into sfdx-project.json and register the package with the sfp server. Each of them takes --repository — the repository the package belongs to, as owner/repo for GitHub and GitLab or org/project/repo for Azure DevOps. It defaults to the GITHUB_REPOSITORY or GITLAB_REPOSITORY environment variable, so it can be omitted in a pipeline but has to be supplied when running locally.

These flags are common to all four commands:

• -n, --name (required): Package name
• -r, --path (required): Directory path for the package
• -d, --description: Package description
• --domain: Name of the release config the package belongs to — takes a value, for example --domain release-config-frameworks
• --repository: Repository identifier, as described above
• -b, --branch: Branch to register the package against
• --no-insert: Do not write the entry into sfdx-project.json
• --insert-after: Insert the entry after a named package

Source Package

sfp package create source -n "my-source-package" -r "src/my-package" --repository myorg/myrepo

# Attached to a release config
sfp package create source -n "my-source-package" -r "src/my-package" --domain release-config-sales --repository myorg/myrepo

Takes the common flags only.

Unlocked Package

sfp package create unlocked -n "my-unlocked-package" -r "src/my-package" --repository myorg/myrepo

# Org-dependent unlocked package
sfp package create unlocked -n "my-package" -r "src/my-package" --org-dependent --repository myorg/myrepo

# Without a namespace
sfp package create unlocked -n "my-package" -r "src/my-package" --no-namespace --repository myorg/myrepo

Additional flags:

• --org-dependent: Create the package as org-dependent
• --no-namespace: Create the package without a namespace
• --error-notification-username: Username to notify on package creation errors

Data Package

sfp package create data -n "my-data-package" -r "data/my-data-package" --repository myorg/myrepo

Takes the common flags only.

Ensure your data package directory contains an export.json and the required CSV files. See Data Packages for details.

Diff Package

sfp package create diff -n "my-diff-package" -r "src/my-diff-package" --commit-id "baseline-commit-id" --repository myorg/myrepo

Additional flags:

• --commit-id: Commit the diff is calculated from

Best Practices

1. Use descriptive names: Package names should clearly indicate their purpose
2. Organize by domain: Group related packages using domains
3. Version consistently: Version numbers are four-part — MAJOR.MINOR.PATCH.BUILD, where the build segment is usually NEXT
4. Choose the right type:

   • Source packages for most metadata
   • Unlocked packages for distributed, versioned components
   • Data packages for reference data
   • Diff packages for selective deployments

Next Steps

• Defining a Domain - Organize packages into domains
• Building Artifacts - Build deployable artifacts from packages
• Package Types - Learn more about different package types