Salesforce Unlocked Packages

Step By Step guide to create and release a Salesforce Unlocked Package

Salesforce Packages are typically utilized to move metadata from one Salesforce org to another. A package can be described as a set of features and customizations (refer to Figure 1) grouped together and ready to be installed in different orgs.

Figure 1 : Package exemple

Unlocked packages are a category of Salesforce packages that can contain almost all types of Salesforce metadata (note that some types are not handled by unlocked packages). They can be installed in any type of org :

• Scratch org
• Sandbox
• Developer edition
• Trial org
• Production org

Upon installation, the admin has the ability to make direct changes to the metadata, which is why they are referred to as ‘unlocked. Once uninstalled, all metadata contained in the unlocked package gets deleted from the org. To uninstall unlocked packages successfully some conditions need to be met (check this article).

Do not use unlocked packages if you are planning to distribute your app on AppExchange, they are especially suited for internal business apps.

Now that we understand what are unlocked packages, it’s time to move to the cool part, creating some unlocked packages :)

Before we start

Before we start, you must make sure everything is set up correctly :

• You need a Dev Hub org (production or developer edition). In your org, enable “Dev Hub” and “Unlocked Packages and Second-Generation Managed Packages”.
• Your user needs to have the “Create and Update Second-Generation Packages” permission (If you’re connecting with an Admin profile then you already have it).
• On your computer, make sure Salesforce CLI is already installed.
• On your computer, make sure Visual Studio Code is already installed.

Follow these steps

1- Create DX project

I’ve already created a DX project and push it to GitHub. You can test with my project :

git clone https://github.com/n-mehadjibia/Unlocked-Package-Project.git

This project contains an Apex class “MathService” and its test class “MathServiceTest”.

If you want to create your own project, follow the steps in this article.

2- Authorize a Dev Hub org

I’m using a developer edition org as my Dev Hub. From VS code menu go to :

• View -> Command Palette
• On the search bare type : SFDX : Authorize a Dev Hub
• Click on : SFDX : Authorize a Dev Hub
• Choose an Alias for your Dev Hub then press enter
• Finally, you will be prompt to login to your Dev Hub org.

Here’s another way to do it :

sf org login web --set-default-dev-hub --alias UnlockedPackageDevHub

3- Create a scratch org

In this step we are supposed to develop and test the package, we can also retrieve from the scratch org the components that we want to include in our package. Here’s how to create a scratch org :

From VS code menu go to :

• View -> Command Palette
• On the search bare type : SFDX : Create a default scratch org
• Click on : SFDX : Create a default scratch org
• Choose an Alias and a duration for your scratch org

Here’s another way to do it :

sf org create scratch --definition-file config/project-scratch-def.json --duration-days 30 --alias MyScratchOrg --target-dev-hub UnlockedPackageDevHub

4- Select the scratch org as your default org

5- Deploy the project in the scratch org

sf project deploy start -d ./force-app

You have to make sure that your test classes are running correctly and covering at least 75% of your package’s Apex code otherwise you won’t be able to release the package later.

6- Package creation

sf package create --name "My Unlocked Package" --path force-app --package-type Unlocked

Your DX project’s “sfdx-project.json” file will be updated after the creation of the unlocked package.

The Dev Hub org against which you run the sf package create command becomes the owner of the package. If the Dev Hub org associated with a package expires or is deleted, its packages will no longer work.

7- Package version creation

In order to install our unlocked package in Salesforce orgs we need to create a package version, but before that let’s update the version name and the version number in the “sfdx-project.json” file :

"versionName": "Winter 24",
"versionNumber": "1.0.0.NEXT"

Here’s the sfdx command that creates a package version :

sf package version create --package "My Unlocked Package" --path force-app --installation-key test1234 --wait 10

Don’t forget to change the installation key (it’s value in the previous sfdx commande was test1234) and to memorize it, we will need it during the installation of the package. You can create a package version without an installation key by adding ( — installation-key-bypass) to your package version create sfdx commande.

After version creation, your project “sfdx-project.json” file will look like this :

Each newly created package version is marked as Beta version, therefore it cannot be installed in production orgs, it can only be installed in : dev, sandbox and scratch orgs. Solely released package versions can be installed in production orgs.

8- Package release

Package versions that can be released must have an Apex code coverage of at least 75%. Code coverage computation is run during the creation of a new package version.

To compute code coverage we must add “ — code-coverage” to the “sf package version create” commande :

sf package version create --package "My Unlocked Package" --path force-app --installation-key test1234 --wait 10 --code-coverage

Now we can release the newly created package version :

sf package version promote --package "My Unlocked Package@1.0.0-2"

9- Install the package in an org

Here’s how our “sfdx-project.json” file looks like right now :

Package version 1.0.0–1 is a Beta version, where as package version 1.0.0–2 is a released version.

Let’s install package version 1.0.0–2 in the dev hub org that we’ve authorized in step 2 :

sf package install --wait 10 --publish-wait 10 --package "My Unlocked Package@1.0.0-2" --installation-key test1234 --no-prompt --target-org UnlockedPackageDevHub

Beta versions and released versions are installed in the same way.

Now, if you open the dev hub org and go to : Setup -> Apps -> Packaging -> Installed Packages, you will find “My Unlocked Package” among the installed packages :

If you want to uninstall the package, simply click on “Uninstall” :

As we mentioned in the intro, to uninstall unlocked packages successfully some conditions need to be met (check this article).

Conclusion :

In this article, we covered the basic workflow of Unlocked Packages creation, release and installation. If you want to learn more about Unlocked Packages, I recommande you read :

Salesforce official documentation for Unlocked Packages.