Create a Namespaced Scratch Org

In this exercise, you will…

  • Add your Packaging Org’s namespace to sfdx-project.json
  • Use the CLI to create a namespaced scratch org
  • Forget to link your namespace to your Dev Hub? You might see this error…

Add your Packaging Org’s namespace to sfdx-project.json

Namespaced Scratch Orgs are one of the key benefits for ISVs building managed packages on Salesforce DX. Creating a namespaced scratch org requires us to update your project’s sfdx-project.json file.

Replace the contents of sfdx-project.json by copy/pasting the following:

Important: Make sure to use YOUR packaging org’s namespace in place of YOUR_NS_HERE

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

After modifying sfdx-project.json, VS Code should look something like this:

  1. In the VS Code Explorer, click on the sfdx-project.json file.
  2. Your updated version of sfdx-project.json should be set with the namespace of your packaging org.

Use the CLI to create a namespaced scratch org

Namespaced scratch orgs are created with the same force:org:create command that you’ve used before. The difference now is that your sfdx-project.json file has a namespace specified in it.

Execute this command:

sfdx force:org:create -a PkgScratch -s -f config/project-scratch-def.json
Salesforce DX Command / Flags Description
force:org:create Creates a scratch org using values specified in a configuration file
-a (setalias) Sets an alias for for the created scratch org.
-s (setdefaultusername) Sets the created org as the default username.
-f (definitionfile) Path to a scratch org definition file.

After executing the above, your terminal should look something like this:

If you get this error, it means that you did not link your packaging org’s namespace to the Dev Hub you used to try to create the namespaced scratch org with.

Updated: