Salesforce DX Project Configuration

We provide sample sfdx-project.json files in the sample repos for creating a project using the CLI or 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.

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 to change the callback URL.

packageDirectories (required)

Package directories indicate which directories to target when syncing source to and from the scratch org. These directories can contain source from your managed package, unmanaged package, or unpackaged source, for example, ant tool or change set.

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.
• The CLI uses the default package directory as the target directory when pulling changes in the scratch org to sync the local project. This default path is also used when creating second-generation packages.
• If you do not 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.

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

sfdcLoginUrl (optional)

The login URL that the force: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 do not specify a default login URL here, or if you run force: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, an icon field was added to the CustomTab for API version 14.0. If you retrieve components for version 13.0 or earlier, you’ll see errors when running the source commands because the components do not include the icon field.

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