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 project deploy and project retrieve 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.

For example, if you upload a static resource archive through the scratch org’s Setup UI, the project retrieve start command 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

See Salefsorce Help: Static Resources for more information.

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 so that your XML editor recognizes them as XML files and you can look at them. 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, source format provides an XML version called Case.object-meta.xml. If you have an app called DreamHouse, 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 <object>.object-meta.xml file.

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 that aren’t field translations are placed in a file called <objectTranslation>.objectTranslation-meta.xml.

See Salesforce Help: Translation Workbench for more information.

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 Experience Cloud 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 can have its own CustomLabels.labels-meta.xml file.