Salesforce DX Project Structure and Source Format

Source Transformation

It’s not uncommon for metadata formatted source to be very large, making it difficult to find what you want. If you work on a team with other developers who update the same metadata at the same time, you have to deal with merging multiple updates to the file. If you’re thinking that there has to be a better way, you’re right.

Before, all custom objects and object translations were stored in one large metadata file.

We solve this problem by providing a new source shape that breaks down these large source files to make them more digestible and easier to manage with a version control system. It’s called source format.

A Salesforce DX project stores custom objects and custom object translations in intuitive subdirectories. Source format makes it much easier to find what you want to change or update. And you can say goodbye to messy merges.

Static Resources

Static resources must reside in the /main/default/staticresources directory. The force:source:push and force:source:pull commands support auto-expanding or compressing archive MIME types within your project. These behaviors support both the .zip and .jar MIME types. This way, the source files are more easily integrated in your Salesforce DX project and version control system.

If, for example, you upload a static resource archive through the scratch org’s Setup UI, force:source:pull expands it into its directory structure within the project. To mimic this process from the file system, add the directory structure to compress directly into the static resources directory root, then create the associated .resource-meta.xml file. If an archive exists as a single file in your project, it’s always treated as a single file and not expanded.

This example illustrates how different types of static resources are stored in your local project. You can see an expanded .zip archive called expandedzippedresource and its related .resource-meta.xml file. You also see a couple .jpg files being stored with their MIME type, and a single file being stored with the legacy .resource extension

File Extensions

When you convert existing metadata format to source format, we create an XML file for each bit. All files that contain XML markup now have an .xml extension. You can then look at your source files using an XML editor. To sync your local projects and scratch orgs, Salesforce DX projects use a particular directory structure for custom objects, custom object translations, Lightning web components, Aura components, and documents.

For example, if you had an object called Case.object, source format provides an XML version called Case.object-meta.xml. If you have an app call DreamHouse.app, we create a file called DreamHouse.app-meta.xml. You get the idea.

Traditionally, static resources are stored on the file system as binary objects with a .resource extension. Source format handles static resources differently by supporting content MIME types. For example, .gif files are stored as a .gif instead of .resource. By storing files with their MIME extensions, you can manage and edit your files using the associated editor on your system.

You can have a combination of existing static resources with their .resource extension, and newly created static resources with their MIME content extensions. Existing static resources with .resource extensions keep that extension, but any new static resources show up in your project with their MIME type extensions. We allow .resource files to support the transition for existing customers. Although you get this additional flexibility, we recommend storing your files with their MIME extensions.

Custom Objects

When you convert from metadata format to source format, your custom objects are placed in the <package directory>/main/default/objects directory. Each object has its own subdirectory that reflects the type of custom object. Some parts of the custom objects are extracted into in these subdirectories:

• businessProcesses
• compactLayouts
• fields
• fieldSets
• listViews
• recordTypes
• sharingReasons
• validationRules
• webLinks

The parts of the custom object that aren’t extracted are placed in a file.

• For objects, <object>.object-meta.xml
• For fields, <field_name>.field-meta.xml

Custom Object Translations

Custom object translations reside in the <package directory>/main/default/objectTranslations directory, each in their own subdirectory named after the custom object translation. Custom object translations and field translations are extracted into their own files within the custom object translation’s directory.

• For field names, <field_name>.fieldTranslation-meta.xml

• For object names, <object_name>.objectTranslation-meta.xml

The remaining pieces of the custom object translation are placed in a file called <objectTranslation>.objectTranslation-meta.xml.

Aura Components

Aura bundles and components must reside in a directory named aura under the <package directory> directory.

Lightning Web Components

Lightning web components must reside in a directory named lwc under the <package directory> directory.

ExperienceBundle for Lightning Communities

The ExperienceBundle metadata type must reside in a directory named experiences under the <package directory> directory. The experiences directory contains a folder for each Lightning community in your org. See the Lightning Communities Developer Guide for details.

Documents

Documents must be inside the directories of their parent document folder. The parent document folder must be in a directory called documents. Each document has a corresponding metadata XML file that you can view with an XML editor.

Custom Labels

All custom labels are contained in a single file called CustomLabels.labels-meta.xml that resides in a directory named labels under the <package directory> directory. Each package directory has its own CustomLabels.labels-meta.xml file. We think it’s easier for you to maintain your custom labels in a single file rather than decomposed into individual files. It also minimizes file I/O performance degradation, especially on Windows.