Create New Versions of an Unlocked Package

A package version is a fixed snapshot of the package contents and related metadata. The package version lets you manage changes and track what’s different each time you release or deploy a specific set of changes.

Before you create a package version, first verify package details, such as the package name, dependencies, and update the versionNumber parameter in the sfdx-project.json file. Verify that the metadata you want to change or add in the new package version is in the package’s main directory.

When you create a package version, you have three options regarding how package validations are handled.

(Default) Complete all validations of dependencies, package ancestors, and metadata before the package version is returned.
Perform validations asynchronously.
Skip validation on the package version.

Create an Unlocked Package Version (Default Option)

Create the package version with this command. Specify the package alias or ID (0Ho). You can also include a scratch definition file that contains a list of features and setting that the metadata of the package version depends on.

1sf package version create --package "Expenser App" --installation-key “HIF83kS8kS7C” \
2--definitionfile config/project-scratch-def.json --code-coverage --wait 10

When creating a package version, specify a --wait time to run the command. If the package version is created within that time, the sfdx-project.json file is automatically updated with the package version information. If not, you must manually edit the project file.

Note

It can be a long-running process to create a package version, depending on the package size and other variables. You can easily view the status and monitor progress.

1sf package version create report --package-create-request-id 08cxx00000000YDAAY

The output shows details about the request.

1=== Package Version Create Request
2NAME                            VALUE
3─────────────────────────────   ────────────────────
4Version Create Request Id       08cB00000004CBxIAM
5Status                          InProgress
6Package Id                      0HoB00000004C9hKAE
7Package Version Id              05iB0000000CaaNIAS
8Subscriber Package Version Id   04tB0000000NOimIAG
9Tag                             git commit id 08dcfsdf
10Branch
11CreatedDate                     2024-05-08 09:48
12Installation URL
13https://login.salesforce.com/packaging/installPackage.apexp?p0=04tB0000000NOimIAG

You can find the request ID (08c) in the initial output of sf package version create.

Depending on the size of the package and other variables, the create request can take several minutes. When you have more than one pending request to create package versions, you can view a list of all requests with this command.

1sf package version create list --created-last-days 0

Details for each request display as shown here (IDs and labels truncated).

1=== Package Version Create Requests [3]
2ID     STATUS  PACKAGE2 ID PKG2 VERSION ID SUB PKG2 VER ID TAG BRANCH CREATED DATE ===
308c... Error   0Ho...
408c... Success 0Ho... 05i... 04t...                                   2024-06-22 12:07
508c... Success 0Ho... 05i... 04t...                                   2024-06-23 14:55

Async Validation

Async validation creates a new package version before completing package validations. If your development team is using continuous integration (CI) scripts, you can leverage async validation to get an installable artifact sooner so you can start post-package creation steps.

To specify async validation, include the - -async-validation parameter.

1sf package version create --async-validation <rest of command syntax>

Sample Command-Line Output

1Version create.... Create version status: PerformingValidations
2The validations for this package version are in progress, but you can now begin testing this package version.
3To determine whether all package validations complete successfully, run "sf package version create report --package-create-request-id  08cxx", and review the Status.
4Async validated package versions can be promoted only if all validations complete successfully.
5Successfully created the package version [08cxx. Subscriber Package Version Id: 04txx
6Package Installation URL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04txx
7As an alternative, you can use the "sf package:install" command.

The command-line output provides you a package creation request ID that starts with 08c. To confirm whether all package validations complete successfully, use the 08cxx ID when and run sf package version create report --package-create-request-id 08cxx. Then validate that the Status is listed as Success. Async validated package versions can be promoted only if all validations complete successfully.

Skip Validation

Skips validation of dependencies, package ancestors, and metadata during package version creation. Skipping validation significantly reduces the time it takes to create a new package version, but package versions created using skip validation can’t be promoted to the released state.

1sf package version create --skip-validation <rest of command syntax>

You can’t specify both skip validation and code coverage, because code coverage is calculated during validation.

You also can’t specify both skip validation and async validation at the same time.

Note

Use Keyword NEXT to Ensure Package Version Numbers Are Unique

To ensure your version number is unique, use the keyword NEXT when you set the version number in your sfdx-project.json file.

For example, "versionNumber": "1.2.0.NEXT".

If you don’t use NEXT, and you also forget to update the version number in your sfdx-project.json file, the new package version uses the same number as the previous package version. Although we don’t enforce uniqueness on package version numbers, every package version is assigned a unique subscriber package version ID (starts with 04t).

How Many Package Versions Can I Create Per Day?

Run this command to see how many package versions you can create per day and how many you have remaining.

1sf limits api display

Look for the Package2VersionCreates entry.

1NAME                                   REMAINING  MAXIMUM
2─────────────────────────────────────  ─────────  ─────────
3Package2VersionCreates                  23         50

Simplify Unlocked Package Development by Creating and Specifying an Org Shape

If your package’s metadata depends on a complex set of features, settings, or licenses, it can be difficult to declaratively specify these dependencies in a scratch org definition file. Instead, create an org shape of your production org, or another development org, and specify that source org’s ID in your scratch org definition file. During package creation, we mimic the source org’s environment when we build and validate your package’s metadata.
Use Branches in Unlocked Packaging

Development teams who use branches in their source control system (SCS), often build package versions based on the metadata in a particular branch of code.
Target a Specific Release for Your Unlocked Packages During Salesforce Release Transitions

During major Salesforce release transitions, you can specify preview or previous when creating a package version. Specifying the release version for a package allows you to test upcoming features, run regression tests, and support customers regardless of which Salesforce release their org is on. Previously, you could only create package versions that matched the Salesforce release your Dev Hub org was on.