Release Your Updated Package

Configure the SFDX-Project.JSON File

Think of a package as a stand-alone application, or a collection of metadata items that you can release on its own without having to release all packages. Packaging metadata makes your deployment process succinct and easier to manage. Packages are organized in a variety of ways, such as by app, by shared library, or by feature. However you organize your metadata packages, it’s important to have the sfdx-project.json file set up correctly so you can create and release new versions of your package.

Let’s configure the sfdx-project.json file so that you can create a new version of your package.

  1. In VS Code, open the sfdx-project.json file and examine the contents in the editor. Notice the name and Id of the package you created.
    The sfdx-project.json file lists the salesApps package and its Id under packageAliases.

  2. Change the versionName to Version 1.0 and change the versionNumber to 1.0.0.NEXT.
    "versionName": "Version 1.0",
    "versionNumber": "1.0.0.NEXT"

  3. 3. Save your changes.
    The sfdx-project.json file reflects the new versionName and versionNumber.

Create a New Version of Your Package

Before you deploy the salesApps package to your playground, you create a new version of the package. 

  1. Run this command, which can take several minutes:
    sfdx force:package:version:create -p salesApps -d force-app -k test1234 --wait 10 -v DevHub --codecoverage
    The terminal window displays the request status and identifies the new package version name. The sfdx-project.json is updated with a new package version listed under packageAliases.
    The terminal window displays request status, identifies the new package version Id and states that the sfdx-project.json file is updated.

  2. Examine the sfdx-project.json file. You should see a new entry under packageAliases.
    In this example, the new package version salesApps@1.0.0-1 has been added to the packageAliases list.
    The sfdx-project.json file. The version number salesApps@1.0.0-1 has been added to the packageAliases list.
    Next, let’s promote the package version and release the package in your Trailhead Playground.

Promote and Release the Package

Your package is almost ready for production—in this case, production is your Dev Hub-enabled Trailhead Playground. Before you install a package in a production org, you must promote the package version.

  1. Promote your package version.
    sfdx force:package:version:promote -p salesApps@1.0.0-1 -v DevHub
    Take note of the salesApps@1.0.0-1 name. When promoting a package version, you use the package name as stated on the sfdx-project.json file.
  2. When prompted if you’re ready to release the package, enter Y.
    Terminal window prompt to release the package and displaying the result “Successfully promoted the package version, ID: <Id number>, to released.”

Now that you’ve promoted the package version to released status, you can install the package in a production org!

  1. Install the unlocked package in your Dev Hub org.
    sfdx force:package:install --wait 10 --publishwait 10 --package salesApps@1.0.0-1 -k test1234 -r -u DevHub
  2. If your Trailhead Playground isn’t already open, open it now.
    sfdx force:org:open -u DevHub
  3. In your Trailhead Playground, check the Installed Packages list (in Setup) to confirm that the package was installed. You should see salesApps with the version number 1.0.
    The Installed Packages list, showing the salesApps package version 1.0 installed.

Now you can roll out your package to production orgs! As you create more metadata components and build apps, you may want to release updates to your package. To release package updates, you create a new version of the package and promote the package version to released status. Then the package is ready to be installed.

That’s a Wrap 

Whoa! That was a lot to unpack (pun intended). Congratulations! You just used the Salesforce CLI to release an unlocked package that contains a new permission set!


Keep learning for
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities