What is a Salesforce DX “Project”?

March 20, 2018 nisarkhan SFDX, 0

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:

1. 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.
2. 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’s sfdx-project.json file.
3. 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.jsonfor 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. 🙂

 

Favorite

available security features in salesforce! Salesforce DX “If you’re a Customer”