The project configuration file is a blueprint for your project. The settings in the file create an outline of your package and determine the package attributes and package contents.
Here are the parameters you can specify in the project configuration file.
None. If your package has an associated branch, but your package dependency is associated with a different branch, or if your package has an associated branch but your package dependency doesn’t, set the branch value accordingly. See Use Branches in Unlocked Packaging
calculateTransitiveDependencies
No
False. Enables the calculation of the package’s indirect dependencies. A package can have multilevel dependencies where pkgC depends on pkgB, and pkgB depends on pkgA. By default, you list all of a package’s dependencies, including indirect (transitive) dependencies. When calculateTransitiveDependencies is set to true, you specify a package’s direct dependencies only, and the indirect dependencies are calculated for you. See the dependencies parameter’s description for example configurations in the sfdx-project.json file. calculateTransitiveDependencies also enables you to generate a hierarchical graph of a package version’s dependencies. To generate the dependencies graph, run the package version displaydependencies CLI command. See package version displaydependencies in the Salesforce CLI Command Reference.
default
Yes, if you’ve specified more than one package directory
true. Indicates the default package directory. Use the sf project retrieve 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.
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.
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. To specify dependencies for unlocked packages outside of the Dev Hub, use a package alias that includes the version. 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, or 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. If you set the calculateTransitiveDependencies parameter to true, you specify the package’s direct dependencies only, and the indirect (transitive) dependencies are calculated for you. See Extract Dependency Information from Unlocked Packages and Considerations for Promoting Packages with Dependencies.
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.
namespace
no
None. A 1–15 character alphanumeric identifier that distinguishes your package and its contents from packages of other developers.
package
Yes
The package name specified in the project json file.
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 sf package commands.
path
Yes
If you don’t specify a path, Salesforce CLI uses a placeholder when you create a package.
postInstallUrl
No
None. A URL to post-install instructions for subscribers.
releaseNotesUrl
No
None. A URL to release notes.
seedMetadata
No
None. Specify the path to your seedMetadata directory. Seed metadata is available to standard value sets only. If your package depends on standard value sets, you can specify a seed metadata directory that contains the value sets.
If not specified, the CLI uses versionNumber as the version name.
versionNumber
Yes
The versionNumber field sets the version number that is assigned the next time you create a new version. Version numbers are formatted as MAJOR.MINOR.PATCH.BUILD. For example, 1.2.1.8. To avoid creating multiple package versions with the same MAJOR.MINOR.PATCH.BUILD number, you must increment the versionNumber before creating a new package version. To automatically increment the build number to the next available build for the package, use the keyword NEXT (1.2.1.NEXT). Alternatively, when you create a new package version, you can set the version number using the --versionNumber flag in the CLI. For more details, see Guidance for Version Numbering.
Note: You can use the LATEST keyword for the version number to set the dependency.
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 sf project generate CLI command to generate a project file that you can build upon. Here’s how the parameters in packageDirectories appear.
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.
j