DX Project
A DX Project (Salesforce DX Project) is a local directory structure recognized by Salesforce CLI ("sf", historically "sfdx" before the 2023 unification) as the container for Salesforce source code and configuration.
Definition
A DX Project (Salesforce DX Project) is a local directory structure recognized by Salesforce CLI ("sf", historically "sfdx" before the 2023 unification) as the container for Salesforce source code and configuration. A DX Project is defined by a sfdx-project.json manifest at its root that declares package directories, source API version, and default org; developers work with metadata as files inside the project, version-control them in Git, and deploy or retrieve via the CLI rather than the Salesforce UI.
In plain English
“A DX Project is the folder on your computer that Salesforce CLI treats as a Salesforce app in source. It has a sfdx-project.json file that says "here's my Apex, my LWCs, my configuration, here's which org to deploy to." You edit the files in your IDE, commit to Git, and use the sf CLI (renamed from sfdx in 2023) to push and pull metadata between the project and your orgs.”
Worked example
A developer at Opalwood Labs clones her team's Salesforce repo and opens the DX Project in VS Code. The sfdx-project.json declares two package directories (force-app and force-common), API version 62.0, and a default Dev Hub alias. She runs "sf project deploy start -o scratch-1" to push the current source to her scratch org, makes a change to a Flow, runs "sf project retrieve start -o scratch-1 --metadata Flow:My_Flow" to pull the change back into source, and commits the diff in Git. The entire loop - edit, deploy, retrieve, commit - happens inside the DX Project directory.
Why DX Project matters
A DX Project is the local-directory foundation of Salesforce development under the DX (Developer Experience) model, where Salesforce metadata is source-of-truth as files in Git rather than configuration in an org UI. The sfdx-project.json manifest declares package directories (source-containing folders that can be tracked separately), the source API version, default username aliases, and packaging configuration. The project tree uses the source format - a decomposed, developer-friendly view of metadata - and the CLI converts to/from the older metadata format automatically when deploying via Metadata API.
Salesforce CLI ships as two commands: the current unified 'sf' (introduced in 2023 as the consolidated CLI, gradually replacing the previous 'sfdx'). DX Projects work identically with either. The DX Project structure also powers Second-Generation Packaging (2GP) - unlocked and managed packages are built directly from DX Project package directories, making source control the source of truth for packaged apps. For modern Salesforce development, the DX Project plus Git plus a CI/CD runner plus Salesforce CLI is the standard stack; Change Sets are a simpler alternative for small, admin-scale deployments between related orgs.
How organizations use DX Project
Maintains their entire Salesforce codebase as a DX Project in GitHub. Every developer works from the same project, runs tests in scratch orgs, and deploys through a GitHub Actions CI/CD pipeline.
Split a large DX Project into multiple unlocked packages using the sfdx-project.json package directories. The split made deployments faster and let different teams own different packages independently.
Uses DX Projects with scratch org automation for their development workflow. New developers clone the project, run a setup script, and have a working scratch org within minutes.
Trust & references
Straight from the source - Salesforce's reference material on DX Project.
- Salesforce DX Developer GuideSalesforce Developers
Test your knowledge
Q1. What is a DX Project?
Q2. What file defines a DX Project's structure?
Q3. Why use DX Projects?
Discussion
Loading discussion…