When working with SFDX, for most of the operations you need to be in a ‘project’. SF CLI will tell you if you are not. But…what makes the directory to BE a SFDX project?

I got no time, just tell me.

Well, TL;DR version of this post is this:

By reading the documentation, you’ll find the information, that the only required property in project-sfdx.json file is packageDirectories.

So:

  1. Create a project-sfdx.json file with packageDirectories property and at least one path
  2. That path must be real. Meaning, that directory HAS to exist

…and that’s it.

You don’t need any sf project generate command, you don’t need to do anything else. That’s the bare minimum and you’re good to go.

sfdx-project.json, version bare minimum:

{
    "packageDirectories": [
        {
            "path": "force-app/"
        }
    ]
}

Fun fact, this directory has to exist, but you still are able to retrieve stuff in different directory, and it will work perfectly fine:

~/Gitrepos/THE-salesforce-project/just-project » sf project retrieve start -o MDAPI -m CustomObject:Account -r force-something

It will create another directory (here, force-something) and retrieve stuff there. Can be useful in CI/CD stuff.

What’s in those project files, exactly?

When you DO decide to do some sf cli magic, you’ll find a command sf project generate and that gives you an option to use one of 3 templates:

  1. empty
  2. standard
  3. analytics
  -t, --template=standard|empty|analytics  Template to use for project creation.

    The template determines the sample configuration files and directories that this command generates. For example, the empty template provides these files and directory to get you started.

    - .forceignore
    - config/project-scratch-def.json
    - sfdx-project.json
    - package.json
    - force-app (basic source directory structure)

    The standard template provides a complete force-app directory structure so you know where to put your source. It also provides additional files and scripts, especially useful when using Salesforce Extensions for VS Code. For example:

    - .gitignore: Use Git for version control.
    - .prettierrc and .prettierignore: Use Prettier to format your Aura components.
    - .vscode/extensions.json: When launched, Visual Studio Code, prompts you to install the recommended extensions for your project.
    - .vscode/launch.json: Configures Replay Debugger.
    - .vscode/settings.json: Additional configuration settings.

    The analytics template provides similar files and the force-app/main/default/waveTemplates directory.

those files might not be required, but for sure are useful and you might simply want to have those in your repository.

  • .forceignore file is similar to .gitignore, but it applies to the deployments.

From docs: The .forceignore file excludes files when running most of the project commands, such as project deploy start, project retrieve start, project convert source, and project delete source.

So, want to have some files on your org, but you want to exclude them from deployments? Or maybe you have some metadata, that is always retrieved, even when not needed? Here you go.

  • config/project-scratch-def.json - this one helps you with working with scratch orgs.

This is the definition of your scratch org, so you can turn some features on and off, tell exactly how do you want your scratch org to look like. You can also have multiple definitions for multiple purposes! You can read more here

Damn, how many times in recent years I’ve said to myself learn more about scratch orgs… It’s still on my todo list.

  • sfdx-project.json is a definition of your project. You can define sourceApiVersion, source directories, namespace and much more. A very cool feature that I should mention here is replacements. That allows you to modify your metadata just for this deployment. That means, you can have some emails, addresses, values that are different for each environment. With this you can replace such value with ENV variable or a file. Neat feature for CI/CD. Read more here.

  • package.json this one is not strictly related to SFDX, but it has its purpose. It is used by Node (which you need to use SF CLI). It installs all the dev dependencies, other ESLints, prettiers etc.

  • .gitignore - this is a GIT file. It defines files (and directories) that should be ignored while commiting. This one is project-wide, so it applies to all devs working on this repository. And it has to be commited of course.

If you want your own exclusions, check .git/info/exclude file - this one is personal.

  • .prettierrc and .prettierignore - both files are used by Prettier to format your code.

prettierrc is a configuration file (like, how do you want your indent, bro?) and prettierignore is what you want to omit during formatting your code. To put it simply. Here you can read about config file, and here about ignoring files.

Last 3 files are related to VSCode itself (which is currently “official” Salesforce IDE. So, I’ll just quote the output of sf project generate --help output:

  • .vscode/extensions.json: When launched, Visual Studio Code, prompts you to install the recommended extensions for your project.
  • .vscode/launch.json: Configures Replay Debugger.
  • .vscode/settings.json: Additional configuration settings.

And there’s that!