Unlocked Packages in Salesforce: A Comprehensive Guide for Developers 

Packaging in Salesforce allows you to install a templated solution for a specific business problem. Salesforce offers different types of packages: first-generation and second-generation packages. 

In this article, we will take a deep dive into Unlocked Packages, which are second-generation packages (2GP).

Key Terms

This article leans into the more technical side of Salesforce. Before we get started, let’s define some key terms, so we are on the same page.

Types of Packages in Salesforce

Managed Packages provide us with templated solutions where certain components are read-only and so can’t be adjusted. They are a great candidate for someone wanting to release a solution on the AppExchange, and you can also push out upgrades.  

Unmanaged Packages allow you to install solutions that are then fully editable in the destination org and so offer more flexibility over Managed Packages. 

Unlocked Packages use a source-control driven model, unlike Unmanaged Packages, and so these don’t rely on a packaging org’s configuration. These packages offer the flexibility to edit metadata, and the provider can push out upgrades should they wish. 

Extension Packages are available and are built on top of an existing Managed Package. 

Salesforce initially introduced 1GP, which uses a UI similar to Change Sets to build out and release. Over the last few years, developers have been switching to 2GP, which uses a source control-driven model that is the standard in many development teams and is managed via Salesforce CLI.

Unlocked Packages Features

An unlocked package is designed for modular, source-driven development. If you are already using CI/CD DevOps Practices, then these packages could slide into existing ways of working relatively easily.

Using the SOAP API, you can push upgrades out to subscribers and decide which orgs receive an upgrade and what version they are migrated to. This is handy if you want to push a hotfix for a known issue, for example. 

Within Unlocked Packages, you can define dependencies on other packages. For example, if your package provides Flows for an object in a managed package, you can define that package as a dependency, which will block installation if the dependent package is not already installed.  

You can define an org-dependent unlocked package to modularize internal configuration in distinct packages, while ensuring they can only be installed in the org in which they originated. This means you can depend on metadata and features such as Multi-Currency. If you ever needed to untangle a package and its dependencies, you can run a SOQL Query on the SubscriberPackageVersion Object to list out dependent packages. 

With Unlocked Packages, you can optionally protect the installation with a password. 

When it comes to namespaces, Unlocked Packages are flexible. You can define a namespace or not – the choice is yours. Just don’t use a namespace to keep existing API Names and for more control over how to distribute the package. Use a namespace to easily define what’s packaged and avoid issues if you have more than one development team. Salesforce suggests working with no namespace or a single namespace to reduce complexity.

Define a postInstallUrl and releaseNotesUrl to provide subscribers with more context within your Unlocked Package. postInstallUrl redirects users after installation, and releaseNotesUrl gives subscribers a place to go for more technical details.

When it comes to Apex, specify unpackaged metadata or access for package version creation. The unpackaged metadata is available to tests, and access gives users the required Permission Sets or Permission Set Licenses to successfully execute tests and create a new version.

Once you create an unlocked package, the associated Dev Hub becomes the owner of that package, meaning if it should later expire or be deleted, the package will no longer work. Transfer packages between different Dev Hubs before an org expires or is deleted to overcome this.

When developing Unlocked Packages, you can define --tag to keep your version control system tags in sync with package versions. You can also use aliases in Salesforce DX Projects so that things are easier to understand, e.g., 0Hoxx00000000CqCAI vs. Opportunity Add On.

If you install ‘Install for Admins Only’, the system will grant access to System Administrators. When setting ‘Install for All Users’, both the System Administrator and all cloned profiles gain access. If you ‘Install for Specific Profiles’, then you get full control over which profiles are granted access.

Unlocked Packages support versions that are like snapshots, with any updates creating new versions. If you remove certain components, then Salesforce will remove them during an upgrade; other components remain in the org but are marked as deprecated. 

You can install Unlocked Packages via CLI, a URL, or a Custom Script. Uninstall using Salesforce Setup or CLI. You can’t uninstall a package if dependencies exist outside the package.

There isn’t currently a path from first-generation packages to second-generation packages, but Salesforce has teased this functionality during the Architect Keynote at Dreamforce 2024.

Final Thoughts

Unlocked Packages are a powerful tool to install metadata in different Salesforce orgs. They are my default whenever packaging solutions, as someone who is familiar with Salesforce CLI.

I’m excited to see what the future holds for this source-control driven way of working that offers the flexibility most organizations or developers expect.

Other Resources

• Unlocked Packages (Salesforce Developers)
• Build Apps Together with Package Development (Trailhead)
• Unlocked Packages (Trailblazer Community)