Creating a package

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:

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:

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.

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