Anatomy of an enterprise SFDX project

The Vitruvian Man — Leonardo da Vinci

I recently faced a challenge of not being able to add a new component from my local filesystem to an already existing SFDX project, in order to be able to push a scratch org.

Soon I discovered that the directory structure was different from the traditional SFDX project structure which is created upon sfdx force:project:create command.

Instead offorce-app/main/default/<all-components>there was a sfdxSrc/* directory. As a matter of fact, the subdirectories and its structure were quite different from the documentation.

The challenge with having a different directory structure was I had no idea where to place the new component metadata(code files), as it would fail on a pushsfdx force:source:push.

Turns out there is flexibility in the directory structure of an SFDX project which is defined in the sfdx-project.json file, which is the configuration file. Here we will find an array named packageDirectories; this setting is called the “Package Directory” which contains the default directory of the source code/metadata where source code is pushed and pulled to and from scratch org.
By default, the package directory marked by default: true 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 saves the SFDX source for your new object locally in your Default Package Directory.

The path to the SFDX source for MyObject__c then looks something like this:

sfdx-project-dir
└─ sfdx-package-dir
   └─ main
      └─ default
         └─ objects
            └─ MyObject__c
               ├─ fields
               └─ MyObject__c.object-meta.xml

Here in case happened to be sfdxSrc/UnmanagedEnter SFDX-Falcon-Template which based on the concept of separating concerns within the project files and folders.

What is SFDX Falcon Template, and why should one use it?

The SFDX Falcon Template uses this concept of “core” and “feature” metadata quite extensively. The idea is that code/metadata that you put in a feature module can depend on what’s in the main module, but not the other way around.

Src: Salesforce DX 201 — Advanced Implementation for ISVs by Vivek Chawla available on Youtube.

Having a custom SFDX-Project directory structure also allows storing developer resources and build tools in their dedicated folders like data import tree, build artifacts and dependencies such ant migration tools and deployment scripts.

Conclusion:

Having a custom directory structure defined in thesfdx-project.json,such as the SFDX-Falcon template allows separation of concerns within a salesforce project. It separates folders for artifacts, documentation, and features while maintaining core metadata and the object model in a single directory.

Got suggestions or need tips on how to effectively leverage SFDX for your salesforce project? Drop a line in the comments below!