Salesforce DX Project Configuration

We provide sample sfdx-project.json files in the sample repos for creating a project using the CLI or IDE.

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": "42.0"
10}

You can manually edit these parameters.

oauthLocalPort

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

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 API format to Salesforce DX project format and from project format to Metadata API format.

namespace

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 or a locked 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

The login URL that the force:auth commands use. 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

The API version that the source is compatible with. 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.