sfdx-project.json

The config file at the root of every source-format project, declaring package directories, namespace, and package dependencies.

Definition

sfdx-project.json is the configuration file every Salesforce CLI command reads at the root of a source-format project. It declares the package directories (where source lives, and which one is the default target for retrieve), the sourceApiVersion, the registered namespace if any, and, for 2GP projects, the list of packages with their aliases and declared dependencies on each other's versions. It's what makes a folder recognizable as a Salesforce project to the CLI, VS Code extensions, and CI tools alike, and it's the file that tracks package version aliases as new versions get created, so a human-readable name maps to the actual version ID Salesforce assigns. A malformed or out-of-date sfdx-project.json is a common source of confusing CLI errors, especially around dependency resolution. Our Salesforce CLI guide covers the file's structure in more depth.

In practice

How it works in Serpent

Serpent reads a project's sfdx-project.json automatically to understand package structure and dependencies, and updates package aliases and version references as builds and promotions happen, so nobody has to hand-edit the file after every release. Multi-package repos with declared dependencies work the same way as single-package ones, without extra configuration. See the Serpent VS Code extension for how project configuration syncs with local development.

Common questions