# Project Configuration File for Unlocked Packages 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. | Name | Required? | Default if Not Specified | | ------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | apexTestAccess | No | None. Assign permission sets and permission set licenses to the user in context when your Apex tests run at package version creation. See [Specify Unpackaged Metadata or Apex Access for Apex Tests (Unlocked Packages)](/docs/platform/sfdx-dev/guide/sfdx-dev-unlocked-pkg-unpackaged-md.md) | | branch | No | 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](/docs/platform/sfdx-dev/guide/sfdx-dev-unlocked-pkg-use-branches.md) | | 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](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_package_version_displaydependencies.md) 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](/docs/platform/sfdx-dev/guide/sfdx-dev-unlocked-pkg-extract-dependency-info.md) and [Considerations for Promoting Packages with Dependencies](/docs/platform/sfdx-dev/guide/dev2gp-considerations-pkg-dependency.md). | | 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. | | unpackagedMetadata | No | None. See [Specify Unpackaged Metadata or Apex Access for Apex Tests (Unlocked Packages)](/docs/platform/sfdx-dev/guide/sfdx-dev-unlocked-pkg-unpackaged-md.md) | | versionDescription | No | None. | | versionName | No | 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](https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_version_guidance.htm). | **Note:** You can use the LATEST keyword for the version number to set the dependency. Example `apexTestAccess`: ```nolang "apexTestAccess": { "permissionSets": [ "Permission_Set_1", "Permission_Set_2" ], "permissionSetLicenses": [ "SalesConsoleUser" ] } ``` Example `branch` when the dependency is on a different branch: ```nolang "dependencies": [ { "package": "pkgB", "versionNumber": "1.3.0.LATEST", "branch": "featureC" } ] ``` Example `branch` when the dependency has no branch: ```nolang "dependencies": [ { "package": "pkgB", "versionNumber": "1.3.0.LATEST", "branch": "" } ] ``` Example `definitionFile`: ```nolang "definitionFile": "config/project-scratch-def.json", ``` Example `dependencies` using a package version alias: ```javascript "dependencies": [ { "package": "MyPackageName@0.1.0.1" } ] ``` Example `dependencies` using a package name and version number: ```javascript "dependencies": [ { "package": "MyPackageName", "versionNumber": "0.1.0.LATEST" } ] ``` Example `dependencies` for a package outside the Dev Hub: ```javascript "dependencies": [ { "package": "OtherOrgPackage@1.2.0" } ] ``` Example `dependencies` with multiple packages in install order: ```javascript "dependencies": [ { "package": "External Apex Library - 1.0.0.4" }, { "package": "Expense Manager - Util", "versionNumber": "4.7.0.LATEST" } ] ``` Example `dependencies` when `calculateTransitiveDependencies` is true: ```javascript "dependencies": [ { "package": "Expense Manager - Util", "versionNumber": "4.7.0.LATEST" } ] ``` Example `includeProfileUserLicenses`: ```nolang "packageDirectories": [ { "package": "PackageA", "path": "common", "versionName": "ver 0.1", "versionNumber": "0.1.0.NEXT", "default": false, "includeProfileUserLicenses": true } ] ``` Example `seedMetadata`: ```nolang "packageDirectories": [ { "seedMetadata": { "path": "my-unpackaged-seed-directory" } } ] ``` 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. ```javascript { "namespace": "", "sfdcLoginUrl": "https://login.salesforce.com", "sourceApiVersion": "61.0", "packageDirectories": [ { "path": "util", "default": true, "package": "Expense Manager - Util", "versionName": "Summer ‘24", "versionDescription": "Welcome to Summer 2024 Release of Expense Manager Util Package", "versionNumber": "4.7.0.NEXT", "definitionFile": "config/scratch-org-def.json" }, { "path": "exp-core", "default": false, "package": "Expense Manager", "versionName": "v 3.2", "versionDescription": "Summer 2024 Release", "versionNumber": "3.2.0.NEXT", "postInstallUrl": "https://expenser.com/post-install-instructions.html", "releaseNotesUrl": "https://expenser.com/summer-2024-release-notes.html", "definitionFile": "config/scratch-org-def.json", "dependencies": [ { "package": "Expense Manager - Util", "versionNumber": "4.7.0.LATEST" }, { "package" : "External Apex Library - 1.0.0.4" } ] } ], "packageAliases": { "Expense Manager - Util": "0HoB00000004CFpKAM", "External Apex Library@1.0.0.4": "04tB0000000IB1EIAW", "Expense Manager": "0HoB00000004CFuKAM"} } ``` ## 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 | | ------------------------- | ---------------------------------------------------------- | | sf package create | SFDX_PROJECT_AUTOUPDATE_DISABLE_FOR_PACKAGE_CREATE | | sf package version create | SFDX_PROJECT_AUTOUPDATE_DISABLE_FOR_PACKAGE_VERSION_CREATE |