So, every DX project by default roughly starts out like this:

    ¦   +---default
    ¦       +---classes
    ¦       +---components
    ¦       +---objects
    ¦       +---pages
    ¦       +---staticresources
    ¦       +---triggers

I know that besides force-app all directories in the root are optional (depending on certain features you want to use or not). Now I wonder about force-app and all the remaining directories.

  • I know that you can have several packages besides force-app so I wonder if force-app is actually a smart name choice, especially if this may get changed later on when everything is split into separate packages.
  • I don't understand the distinction between main and test. So this basically splits up unit tests and the remaining data and metadata of the org? Can I have other directories at this level? If so - which one?
  • Why is there only one directory called default? The default for what? Can we have non-defaults? What kind of other directories can I have at that level?
  • Is it correct that - compared to non-DX - that there's no src directory anymore? Is this always the case? Is default kind of doing what src did before?
  • Is it correct that main and default are always empty file-wise?

Maybe these are stupid questions but since I'm in the middle of a huge conversion right now I want to minimize the hustle afterwards for me and my colleagues. Moving whole trees around in the repository is no joke.

  • 3
    What documentation have you checked? Have you seen this: developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/… ? Sep 25, 2020 at 15:05
  • This helps a little bit but I still have a lot of confusion, especially regarding this: "How you organize your local source code among these directories takes more thought and planning, and depends on your development environment. Plan how to organize your code before you get started." So - I already have all my code. This project is 10 years old. How can I get a thoughtful directory layout without having to change too much later on when I separate things into packages?
    – Semmel
    Sep 25, 2020 at 15:11
  • Baby steps, start from where you know, then keep improving from there on. Sep 26, 2020 at 7:25

2 Answers 2


The directory structure force-app/main/default is an example. You do not have to follow this structure. You can use your own structure as long as you have the path specified in the sfdx-project.json file in your project.

If you plan to use multiple unlocked packages, it makes sense to locally organize them into multiple package directories.

Breaking 10000s of components into multiple packages is not a simple task that you can solve in a day or a week in large complex implementation.

You need a lot of planning and strategy to organize into multiple packages. The advantages you get are Modularity and agility and use salesforce packaging technology like unlocked packages.

There are various architectural strategies like

  1. Horizontal slicing
  2. Vertical Slicing.

Check the last 10 minutes of this session

It's also totally ok to just have one package as a whole for now but note that once you keep growing you will see that you won't be able to release at the agile speed with which you want.

In fact, we now provide org dependent unlock pages so you do not have to worry about breaking the entire monolith to adopt package based development.


This is a great question; I had dig around a lot to determine what capabilities and best practices surround the new DX file structure. I don't recall my sources on what I learned, so I can't list them here. But here's what I found through research and trial/error.

First, we have a great deal of freedom in designing the structure, but the weirder you make your DX structure, the more likely it is that you'll encounter a DX quirk / undocumented limitation. In the structure you listed, "force-app" is similar to the src directory in that all source should (as a best practice) go under one central directory. This helps with e.g. managing the project as a git repository etc. In terms of the name, I also didn't like it, so I went with "sfdx-source".

The meaning of the next level is up to you. Because I have multiple packages in my project, I made one directory per package. Within those packages, you can organize your directory structure in whatever way you like. Here's an example of how I structured things:

enter image description here

The key is that you need to maintain a "default" directory for metadata that is created through the UI. For example, if you create a new object in a scratch org, then download the source to your local machine, SFDX needs to know where to place that object.

For my preferences, I wanted all metadata/code to start in an "unpackaged" directory. When I was ready to add the metadata to a package, I would move it to the appropriate package directory (through a file browser). The one "gotcha" I experienced with this is that SFDX has trouble with moving object metadata from one place to another. As of the last time I worked in DX, every time I needed to move a new object to its final home, I had to recreate my scratch org in order for the metadata to properly sync again.

The package source directories are defined in sfdx-project.json. You specify a root directory for each package, and the system will act appropriately regardless of how you choose to organize it. The only "package" that requires a particular structure is the default package. It may be possible to change the structure or names of the folders there, but from everything I've seen you have to have a "main/default" directory in the default package.

Here is what my JSON looks like, corresponding to the directories previously shared:

enter image description here

Finally, concerning main and default, these directories do not need to be empty file-wise; you can move metadata files into those directories if you like, or (more likely) include non-metadata files like a .gitignore. The system will parse whatever directory structure is there, and deploy any metadata/code with the appropriate file extensions. The only difference between main and test is that main is a special directory that contains the default directory. test on the other hand is a directory to which you might move any apex tests after they were created in main/default. In my case, I prefer to have all my unit tests in the same directory as the classes that they're testing, so I don't have a test directory.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.