Salesforce DX Developer Guide

How Salesforce Developer Experience Changes the Way You Work
Set Up Salesforce DX Tools for Developer Users
Project Setup
Sample Repository on GitHub
Create a Salesforce DX Project
Salesforce DX Project Structure and Source Format
How to Exclude Source When Syncing
Create a Salesforce DX Project from Existing Source
Convert Files in Metadata Format to Source Format
Salesforce DX Usernames and Orgs
Link a Namespace to a Dev Hub Org
Salesforce DX Project Configuration
Multiple Package Directories
Replace Strings in Code Before Deploying or Packaging
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Development
Build and Release Your App
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Salesforce DX Project Configuration

The project configuration file sfdx-project.json indicates that the directory is a Salesforce DX project. The configuration file contains project information and facilitates the authorization of orgs and the creation of second-generation packages. It also tells Salesforce CLI where to put files when syncing between the project and org.

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

Are you planning to create second-generation packages? When you’re ready, add packaging-specific configuration options to support package creation. See Project Configuration File for a Second-Generation Managed Package.

Note

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

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 scratch 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. Change this port if 1717 is already in use and you plan to create a connected app in your Dev Hub org to support JWT-based authorization. Be sure you also 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 a Second-Generation Managed Package for details.

packageDirectories (required)

Package directories indicate which directories to target when syncing source to and from the org. These directories can contain source files from your managed or unmanaged package. They can also contain unpackaged source files produced by, for example, an ant tool or change set. For information on all packageDirectories options, see Project Configuration File for a Second-Generation Managed Package.

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.
  • 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 retrieving changes from the org to 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 custom plugins you’ve created 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 plugins’ behavior.

Store configuration variables 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) (Deprecated)

This property is deprecated and applies only to the deprecated force:source:push command. It doesn't affect the behavior of the project deploy start command. To deploy packages sequentially, and in a specific order, use separate project deploy start commands in the desired order.

Note

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:
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 org login commands use. If not specified, the default is https://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 https://test.salesforce.com.

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

sourceApiVersion (optional)

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

The sourceApiVersion value determines the fields retrieved for each metadata type during project deploy, project retrieve, or project 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 58.0. If you retrieve components for version 57.0 or earlier, you see errors when running the project commands because the components don't include that field.

Don’t confuse this project configuration parameter with the org-api-version CLI configuration variable, which has a similar name. See How API Version and Source API Version Work in Salesforce CLI for more information.