Project Configuration File for a Second-Generation Managed Package
Here are some of the parameters you can specify in the project configuration file. For additional parameters, see Advanced Project Configuration Parameters for Second-Generation Managed Packages.
Name | Details |
---|---|
ancestorId |
Required? It depends on whether you’ve already promoted a package version
of this package. If yes, you must specify either the ancestorId or ancestorVersion. If
no, this parameter isn’t required. Default if Not Specified: None None. The ID of the immediate parent in the package ancestry tree of the package version you’re creating. The ancestorId requires the 04t of the package version, or an alias to the package version. When specifying ancestors, you can use either ancestorId or ancestorVersion.Example:
For more information, see Specify a Package Ancestor in the Project File for a Second-Generation Managed Package. |
ancestorVersion |
Required? It depends on whether you’ve already promoted a package version
of this package. If yes, you must specify either the ancestorId or ancestorVersion. If
no, this parameter isn’t required. Default if Not Specified: None The version number of the immediate parent in the package ancestry tree of the package version you’re creating.Specify the ancestor version using the format of major.minor.patch.build. When specifying ancestors, you can use either ancestorId or ancestorVersion. Example:
For more information, see Specify a Package Ancestor in the Project File for a Second-Generation Managed Package. |
default |
Required? Yes, if you’ve specified more than one package
directory Default if Not Specified: true Indicates the default package directory. When metadata is retrieved from a development org (scratch org or source-tracked sandbox) using sf project retrieve, it's placed in the default package directory. There can be only one package directory in which the default is set to true. |
definitionFile |
Required? No Default if Not Specified: 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:
|
namespace |
Required? Yes Default if Not Specified: None A 1–15 character alphanumeric identifier that distinguishes your package and its contents from packages of other developers. |
package |
Required? Yes Default if Not Specified: None The package name is specified in the project json file. |
packageAliases |
Required? No Default if Not Specified: Salesforce CLI updates this file with the 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 |
Required? Yes Default if Not Specified: None. Specify the location that contains the package metadata in the --path attribute of sf package create Salesforce CLI command. |
seedMetadata |
Required? No Default if Not Specified: 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. Example:
|
versionDescription |
Required? No Default if Not Specified: None |
versionName |
Required? No Default if Not Specified: If not specified, the CLI uses versionNumber as the version name. |
versionNumber |
Required? Yes Default if Not Specified: None The versionNumber field sets the version number that is assigned the next time you create a 2GP 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. |
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 is 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.
{
"namespace": "exp-mgr",
"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",
"ancestorVersion": "3.0.0.7",
"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 |