How to Create/Version/Install Your First Unlocked Package

 

Why Unlocked Package?

Modular 

Unlocked packages organize your code and metadata in modular way. 

Reusable

These packages could be installed on different environments.

Best suited for AGILE development
Write-once-install-anywhere

Read more in - What is unlocked package?

Before we start, make sure you have DevHub enabled org with second generation packaging enabled on devhub org.

You built your code and metadata in salesforceDX project on local machine. And we are going to create unlocked package containing code and metadata which is there in salesforceDX project.

This code and metadata could be developed and tested by you locally or pulled through any org or scratch org. To learn more about salesforceDX project please visit package based development

Open it with visual studio code editor.

Initial sfdx.project.json file will look like :

 {  
  "packageDirectories": [  
   {  
    "path": "force-app",  
    "default": true  
   }  
  ],  
  "namespace": "",  
  "sfdcLoginUrl": "https://login.salesforce.com",  
  "sourceApiVersion": "46.0"  
 }  

Package directory will store created packages name, version name and number.

default parameter specifies default package to refer.

sfdcLoginUrl gets launched when we try to authenticate and login to devhub org.

Generate the package

force:package:create command used to create package that can be base package or it can depend on existing package.

 sfdx force:package:create --name mypackage --description "My First Package" --packagetype Unlocked --path force-app --nonamespace --targetdevhubusername DevHub  

--packagetype is the type of package

--targetdevhubusername to specify non-default devhub org.

--path specifies folder where your metadata resides

Package will be created with package Id :

 sfdx-project.json has been updated.  
 Successfully created a package. 0Ho0o0000008OSjCAM  
 === Ids  
 NAME    VALUE  
 ────────── ──────────────────  
 Package Id 0Ho0o0000008OSjCAM  

sfdx-project.json updated with package name, version name and number as follows:

 {  
   "packageDirectories": [  
     {  
       "path": "force-app",  
       "default": true,  
       "package": "mypackage",  
       "versionName": "ver 0.1",  
       "versionNumber": "0.1.0.NEXT"  
     }  
   ],  
   "namespace": "",  
   "sfdcLoginUrl": "https://login.salesforce.com",  
   "sourceApiVersion": "46.0",  
   "packageAliases": {  
     "mypackage": "0Ho0o0000008OSjCAM"  
   }  
 }  

Create version of package

In sfdx-project.json change version name to 'mypackage version1.0' and version number to '1.0.0.NEXT' to create first version of your package.

 sfdx force:package:version:create -p mypackage -d force-app -k test1234 --wait 10 -v DevHub  

-p is a package name
-d is a directory
-k is a key for that package which needs to match while installation

success message for creation of package on terminal:

 sfdx-project.json has been updated.  
 Successfully created the package version [08c0o00000000Z7AAI]. Subscriber Package Version Id: 04t0o000003jMTrAAM  
 Package Installation URL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t0o000003jMTrAAM  

In sfdx-project.json packagealiase added for version of package:

  "packageAliases": {  
     "mypackage": "0Ho0o0000008OSjCAM",  
     "mypackage@1.0.0-1": "04t0o000003jMTrAAM"  
   }  

Installation of package with the CLI

For installation of package use force:package:install command

 sfdx force:package:install --wait 10 --publishwait 10 --package mypackage@1.0.0-1 -k test1234 -r -u DevHub  

If publishwait is 0 package installation will fail , unless that package version is already available on your target org.  because publishwait specifies the maximum number of minutes that the command waits for the package version to be available in the target org.  default value is 0 .

--wait defines the maximum number of minutes that the command waits for the installation to complete after the package is available, but the installation continues even though wait time elapses.
you can check status of installation using force:package:install:report

-k is the key of package version
-u target org username or alias