Project Configuration File for Packages

The project configuration file is a blueprint for your project and for the outline of a package. The settings in the file determine the package attributes and package contents.

Here are the parameters you can specify in the project configuration file.

Name	Required?	Default if Not Specified
path	Yes	If you don’t specify a path, Salesforce CLI uses a placeholder when you create a package.
default	Yes, if you’ve specified more than one package directory	true Indicates the default package directory. Use the `force:source:pull` command to copy metadata from your scratch org to your default package directory. There can be only one package directory in which the default is set to true.
package	Yes	The package name specified in the project json file.
versionName	No	If not specified, the CLI uses versionNumber as the version name.
versionDescription	No	None.
versionNumber	Yes	None. Version numbers are formatted as major.minor.patch.build. For example, 1.2.1.8. To automatically increment the build number to the next available build for the package, use the keyword NEXT (1.2.1.NEXT).
dependencies	No	None. Specify the dependencies on other packages. To specify dependencies for unlocked packages within the same Dev Hub, use either the package version alias or a combination of the package name and the version number. `1"dependencies": [ 2 { 3 "package": "MyPackageName@0.1.0.1" 4 } 5]` `1"dependencies": [ 2 { 3 "package": "MyPackageName", 4 "versionNumber": "0.1.0.LATEST" 5 } 6]` To specify dependencies for unlocked packages outside of the Dev Hub use: `1"dependencies": [ 2 { 3 "package": "OtherOrgPackage@1.2.0" 4 } 5]` You can use the LATEST keyword for the version number to set the dependency. Note To denote dependencies with package IDs instead of package aliases, use: The `0Ho` ID if you specify the package ID along with the version number The `04t` ID if you specify only the package version ID If the package has more than one dependency, provide a comma-separated list of packages in the order of installation. For example, if a package depends on the package Expense Manager - Util, which in turn depends on the package External Apex Library, the package dependencies are: `1"dependencies": [ 2 { 3 "package": "Expense Manager - Util", 4 "versionNumber": "4.7.0.LATEST" 5 }, 6 { 7 "package" : "External Apex Library - 1.0.0.4" 8 } 9]` See: Extract Dependency Information from Unlocked Packages
definitionFile	No	None. A reference to an external .json file used to specify the features and org settings required for the metadata of your package, such as the scratch org definition. Example: `1"definitionFile": "config/project-scratch-def.json",`
namespace	no	None. A 1–15 character alphanumeric identifier that distinguishes your package and its contents from packages of other developers.
packageAliases	Yes	Salesforce CLI updates the project file with aliases when you create a package or package version. You can also manually update this section for existing packages or package versions. You can use the alias instead of the cryptic package ID when running CLI `force:package` commands.
releaseNotesUrl	No	None. A URL to release notes.
postInstallUrl	No	None. A URL to post-install instructions for subscribers.
includeProfileUserLicenses	No	False. Setting this parameter to `true` ensures that user licenses associated with profiles in unlocked packages are retained during package version creation. By default, unlocked packages remove profile information not pertinent to the packaged metadata. `1"packageDirectories": [ 2 { 3 "package": "PackageA", 4 "path": "common", 5 "versionName": "ver 0.1", 6 "versionNumber": "0.1.0.NEXT", 7 "default": false, 8 "includeProfileUserLicenses": true 9 } 10]`

When you specify a parameter using Salesforce CLI, it overrides the value listed in the project definition file.

The Salesforce DX project definition file is a JSON file located in the root directory of your project. Use the force:project:create CLI command to generate a project file that you can build upon. Here’s how the parameters in packageDirectories appear.

1{
2   "namespace": "",
3   "sfdcLoginUrl": "https://login.salesforce.com",
4   "sourceApiVersion": "47.0",
5   "packageDirectories": [
6      {
7         "path": "util",
8         "default": true,
9         "package": "Expense Manager - Util",
10         "versionName": "Winter ‘20",
11         "versionDescription": "Welcome to Winter 2020 Release of Expense Manager Util Package",
12         "versionNumber": "4.7.0.NEXT",
13         "definitionFile": "config/scratch-org-def.json"
14      },
15      {
16         "path": "exp-core",
17         "default": false,
18         "package": "Expense Manager",
19         "versionName": "v 3.2",
20         "versionDescription": "Winter 2020 Release",
21         "versionNumber": "3.2.0.NEXT", 
22         "postInstallUrl": "https://expenser.com/post-install-instructions.html",
23         "releaseNotesUrl": "https://expenser.com/winter-2020-release-notes.html",
24         "definitionFile": "config/scratch-org-def.json",
25         "dependencies": [
26            {
27               "package": "Expense Manager - Util",
28               "versionNumber": "4.7.0.LATEST"
29
30            },
31            {
32               "package" : "External Apex Library - 1.0.0.4"
33            }
34         ]
35      }
36   ],
37   "packageAliases": {
38      "Expense Manager - Util": "0HoB00000004CFpKAM",
39      "External Apex Library@1.0.0.4": "04tB0000000IB1EIAW",
40      "Expense Manager": "0HoB00000004CFuKAM"}
41}

What If I Don’t Want My Salesforce DX Project Automatically Updated?

In some circumstances, you don’t want to have automatic updates to the sfdx-project.json file. When you require more control, use these environment variables to suppress automatic updates to the project file.

For This Command	Set This Environment Variable to True
force:package:create	SFDX_PROJECT_AUTOUPDATE_DISABLE_FOR_PACKAGE_CREATE
force:package:version:create	SFDX_PROJECT_AUTOUPDATE_DISABLE_FOR_PACKAGE_VERSION_CREATE

Salesforce DX Developer Guide

Project Configuration File for Packages

What If I Don’t Want My Salesforce DX Project Automatically Updated?