Salesforce DX Project Configuration

We provide sample sfdx-project.json files in the sample repos for creating a project using Salesforce CLI or Salesforce Extensions for VS Code.

We recommend that you check in this file with your source.

1{ 
2"packageDirectories" : [ 
3    { "path": "force-app", "default": true}, 
4    { "path" : "unpackaged" }, 
5    { "path" : "utils" } 
6  ],
7"namespace": "", 
8"sfdcLoginUrl" : "https://login.salesforce.com", 
9"sourceApiVersion": "44.0"
10}

You can manually edit these parameters.

name (required for Salesforce Functions)

Salesforce DX or Salesforce Functions project name.

namespace (optional)

The global namespace that is used with a package. The namespace must be registered with an org that is associated with your Dev Hub org. This namespace is assigned to scratch orgs created with the org:create command. If you’re creating an unlocked package, you have the option to create a package with no namespace.

Register the namespace with Salesforce and then connect the org with the registered namespace to the Dev Hub org.

Important

oauthLocalPort (optional)

By default, the OAuth port is 1717. However, change this port if this port is already in use, and you plan to create a connected app in your Dev Hub org to support JWT-based authorization. Also, don’t forget to follow the steps in Create a Connected App in Your Org to change the callback URL.

packageAliases (optional)

Aliases for package IDs, which can often be cryptic. See Project Configuration File for Packages for details.

packageDirectories (required)

Package directories indicate which directories to target when syncing source to and from the org. These directories can contain source from your managed package, unmanaged package, or unpackaged source, for example, ant tool or change set. For information on all packageDirectories options, see Project Configuration File for Packages.

Keep these things in mind when working with package directories.

• The location of the package directory is relative to the project. Don’t specify an absolute path. The following two examples are equivalent.
  1"path": "helloWorld" 
  2"path" : "./helloWorld"

• You can have only one default path (package directory). If you have only one path, we assume it’s the default, so you don’t have to explicitly set the default parameter. If you have multiple paths, you must indicate which one is the default.
• Salesforce CLI uses the default package directory as the target directory when pulling changes in the org to sync the local project. This default path is also used when creating second-generation packages.
• If you don’t specify an output directory, the default package directory is also where files are stored during source conversions. Source conversions are both from metadata format to source format, and from source format to metadata format.

plugins (optional)

To use the plug-ins you develop using the Salesforce Plugin Generator with your Salesforce DX project, add a plugins section to the sfdx-project.json file. In this section, add configuration values and settings to change your plug-ins’ behavior.

1"plugins": {
2  "yourPluginName": {
3    "timeOutValue": "2"
4  },
5  "yourOtherPluginName": {
6    "yourCustomProperty": true
7  }
8}

Store configuration values for only those values that you want to check in to source control for the project. These configuration values affect your whole development team.

pushPackageDirectoriesSequentially (optional)

Set to true to push multiple package directories in the order they're listed in packageDirectories when using force:source:push. The directories are pushed in separate transactions. The default value of this property is false, which means that multiple package directories are deployed in a single transaction without regard to order. Example:

1"packageDirectories": [
2    {
3      "path": "es-base-custom",
4      "default": true
5    },
6    {
7      "path": "es-base-ext"
8    }
9  ],
10  "pushPackageDirectoriesSequentially": true,

This property applies only to force:source:push and doesn't affect the behavior of the force:source:deploy command.

See Push Source Sequentially for more information.

Note

replacements (optional)

Automatically replace strings in your metadata source files with specific values right before you deploy the files to an org.

See Replace Strings in Code Before Deploying for details.

sfdcLoginUrl (optional)

The login URL that the auth commands use. If not specified, the default is login.salesforce.com. Override the default value if you want users to authorize to a specific Salesforce instance. For example, if you want to authorize into a sandbox org, set this parameter to test.salesforce.com.

If you don’t specify a default login URL here, or if you run auth outside the project, you specify the instance URL when authorizing the org.

sourceApiVersion (optional)

The API version that the source is compatible with. The default is the same version as the Salesforce CLI.

The sourceApiVersion determines the fields retrieved for each metadata type during source:push, source:pull, or source:convert. This field is important if you’re using a metadata type that has changed in a recent release. You’d want to specify the version of your metadata source. For example, let's say a new field was added to the CustomTab for API version 53.0. If you retrieve components for version 52.0 or earlier, you see errors when running the source commands because the components don't include that field.

Be sure not to confuse this project configuration value with the apiVersion CLI runtime configuration value, which has a similar name.