What is a Salesforce DX “Project”?
In general, a Salesforce DX Project is a new local file structure that collects your org’s metadata (code and config), org templates, sample data, and tests. The project root is often the repository root of a version control system (VCS) as well.
Specifically, an SFDX Project exists when you have a local directory that contains the following:
- A project configuration file. This file is always named
sfdx-project.json
and the directory where it’s located becomes the “root” of that Salesforce DX project. - One or more “Salesforce DX Package Directories”, which contain SFDX source. These directories live within the SFDX project root, contain SFDX source, and must be explicitly declared as “Package Directories” by adding their path(s) to the
packageDirectories
array inside the project’ssfdx-project.json
file. - A hidden directory named
.sfdx
where the Salesforce CLI keeps a variety of files and directories that support the internal operation of the CLI for that specific Salesforce DX project.
There are a couple more files that you get after running the sfdx force:project:create
command, but the above list describes the minimum set of files and directories that are required to have a functional Salesforce DX project.
What is a Salesforce DX “Package Directory”?
The Salesforce CLI works by scanning all of the Package Directories declared in sfdx-project.json
for locally added or modified SFDX source metadata. It attempts to synchronize that source with any scratch orgs you point the CLI at with sfdx force:source:push
or sfdx force:source:pull
.
Any metadata (Custom Objects, Apex Code, Profiles, etc.) created outside of your SFDX project (like in a scratch org) will be new to the CLI’s internal map of your project’s metadata. When this happens, the CLI needs to have a place to put newly discovered metadata. This is where the Default Package Directory comes in.
What is the “Default Package Directory” and why is it special?
Defined as part of a project’s sfdx-project.json
file, the Default Package Directory is the CLI’s go-to location for storing “Remotely Added” metadata.
For example, if you add a new Custom Object named MyObject__c
to your scratch org using the Setup UI and then run sfdx force:source:pull
, the CLI is going to save the SFDX source for your new object locally in your Default Package Directory.
The path to the SFDX source for MyObject__c
will look something like this:
sfdx-project-dir
└─ sfdx-package-dir
└─ main
└─ default
└─ objects
└─ MyObject__c
├─ fields
└─ MyObject__c.object-meta.xml
The names for sfdx-project-dir
and sfdx-package-dir
will be different for your project, but everything else would look exactly like this. The Salesforce CLI will always use the path main/default/<metadata-type>
inside of your default package directory when storing remotely added metadata. This also happens when you use the sfdx force:mdapi:convert
command to convert MDAPI source to SFDX source.
Without a consistent, known location for the CLI to put remotely added SFDX source, developers would need to pre-define locations for all metadata types. Even if a developer thought of “everything” and defined complex rules for what metadata goes where on a force:source:pull
, you’d still need a generic default just in case they missed something.
In other words, having a clean, simple, consistent default location for remotely added metadata is a feature, not a bug. 🙂
available security features in salesforce! Salesforce DX “If you’re a Customer”