Create Salesforce DX Project

A Salesforce DX project is a local workspace that organizes Salesforce metadata, configuration files, scripts, tests, and package directories. You can create a new project with Salesforce CLI, create one from Visual Studio Code, or clone an existing Salesforce DX repository from GitHub.

Create a Salesforce DX Project with Salesforce CLI

Before creating the project, install Salesforce CLI and confirm that the sf command is available in your terminal.

sf --version

The current Salesforce CLI command for generating a project is sf project generate. The following command creates a project named tutorialkart-salesforce.

sf project generate --name tutorialkart-salesforce

After the command completes, move into the generated project directory.

cd tutorialkart-salesforce

The older sfdx force:project:create command may still appear in existing tutorials and scripts. It creates the same type of Salesforce DX project skeleton.

prasanth:~ prasanth$ sfdx force:project:create -n tutorilkart.com
target dir = /Users/Prasanth
   create tutorilkart.com/sfdx-project.json
   create tutorilkart.com/README.md
   create tutorilkart.com/.forceignore
   create tutorilkart.com/config/project-scratch-def.json

In the older command output above, tutorilkart.com is the project name. Salesforce CLI creates the configuration files and directories automatically; you do not need to create them manually after project generation.

Salesforce DX Project Files and Directories

A newly generated Salesforce DX project commonly contains the following files and directories.

• sfdx-project.json defines package directories, the source API version, namespace settings, package aliases, and other project-level configuration.
• config/project-scratch-def.json contains the definition used when creating a scratch org, including the org edition and enabled features.
• .forceignore lists files and directories that Salesforce CLI should ignore during source operations.
• force-app is the default package directory for Salesforce metadata such as Apex classes, Lightning Web Components, objects, layouts, and permissions.
• README.md can be used to document project setup, development commands, deployment steps, and team conventions.

Salesforce DX Project Directory Structure

A basic Salesforce DX project can have a directory structure similar to the following.

tutorialkart-salesforce/
├── .forceignore
├── README.md
├── config/
│   └── project-scratch-def.json
├── force-app/
│   └── main/
│       └── default/
└── sfdx-project.json

The force-app/main/default directory stores source-format Salesforce metadata by default. A project can also define multiple package directories in sfdx-project.json.

Example sfdx-project.json Configuration

The generated sfdx-project.json file identifies the package directory and API version used by the project.

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "name": "tutorialkart-salesforce",
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "XX.0"
}

Replace XX.0 with the API version required by your installed Salesforce CLI and target org. Avoid changing the source API version without checking whether the metadata in the project is compatible with that version.

Create a Salesforce DX Project in Visual Studio Code

You can create the same project structure through Visual Studio Code when the Salesforce Extension Pack and Salesforce CLI are installed.

1. Open Visual Studio Code.
2. Open the Command Palette using Ctrl+Shift+P on Windows or Linux, or Command+Shift+P on macOS.
3. Run SFDX: Create Project or SFDX: Create Project with Manifest.
4. Select a standard project template when prompted.
5. Enter the Salesforce DX project name.
6. Select the parent folder in which the project should be created.
7. Open the generated project folder in Visual Studio Code.

SFDX: Create Project with Manifest also creates a manifest/package.xml file. This option is useful when retrieving a selected set of metadata from an existing org.

Create a Salesforce DX Project with a Manifest from the CLI

To generate a project that includes a metadata manifest, use the manifest template.

sf project generate --name tutorialkart-salesforce --template manifest

The resulting manifest/package.xml file can be edited to list the metadata types and members that you want to retrieve or deploy.

Create a Salesforce DX Project from Existing GitHub Source

You do not need to generate a new project when a repository already contains sfdx-project.json and the expected Salesforce DX directory structure. Instead, clone the repository and open its project directory.

• Open Terminal on macOS or Linux, or PowerShell, Command Prompt, or Git Bash on Windows.
• Create a parent directory for the local repository if required.

prasanth:~ prasanth$ mkdir tutorialkart_sfdxproject
prasanth:~ prasanth$ cd tutorialkart_sfdxproject

In the example above, tutorialkart_sfdxproject is the parent directory used to store the cloned project.

Clone the sfdx-dreamhouse Salesforce DX Project

Use Git to clone the existing Salesforce DX repository.

prasanth:tutorialkart_sfdxproject prasanth$ git clone 
https://github.com/forcedotcom/sfdx-dreamhouse.git
Cloning into 'sfdx-dreamhouse'...
remote: Counting objects: 2073, done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 2073 (delta 1), reused 3 (delta 0), pack-reused 2062
Receiving objects: 100% (2073/2073), 82.27 MiB | 251.00 KiB/s, done.
Resolving deltas: 100% (851/851), done.
prasanth:tutorialkart_sfdxproject prasanth$

Now the repository pulls every source code into our local system(Mac) as shown below.

After cloning, enter the repository directory and verify that it contains sfdx-project.json.

cd sfdx-dreamhouse
ls

On Windows Command Prompt, use dir instead of ls.

Authorize an Org from the Salesforce DX Project

Creating a project does not automatically connect it to a Salesforce org. To authorize a development, sandbox, or production org through the browser, run the following command from the project directory.

sf org login web --alias MyDevOrg --set-default

For a sandbox, specify the Salesforce test login URL.

sf org login web --instance-url https://test.salesforce.com --alias MySandbox --set-default

Use an alias that clearly identifies the org. The --set-default option makes the authorized org the default target for later commands in the project.

Verify Authorized Salesforce Orgs

List the orgs that are currently authorized in Salesforce CLI.

sf org list

Create a Scratch Org for the Salesforce DX Project

A scratch org is a temporary Salesforce environment created from a scratch definition file. Scratch org creation requires an authorized Dev Hub.

Authorize the Dev Hub and assign it an alias.

sf org login web --set-default-dev-hub --alias MyDevHub

Then create a scratch org using the generated definition file.

sf org create scratch \
  --definition-file config/project-scratch-def.json \
  --alias TutorialScratch \
  --set-default \
  --duration-days 7

The requested features in project-scratch-def.json must be available in the Dev Hub. If scratch org creation fails, review the edition, features, settings, namespace, and Dev Hub configuration.

Retrieve or Deploy Metadata from a Salesforce DX Project

For an existing org, retrieve metadata into the project using a manifest or metadata selectors. The following command retrieves the members listed in manifest/package.xml.

sf project retrieve start --manifest manifest/package.xml --target-org MyDevOrg

To deploy local metadata from the default package directory, run:

sf project deploy start --source-dir force-app --target-org MyDevOrg

Review deployment results and test failures before treating the deployment as complete. Production deployments can require tests depending on the metadata and deployment method.

Open the Salesforce Org from the DX Project

Open an authorized org in the default browser with the following command.

sf org open --target-org MyDevOrg

If a default target org has already been configured, you can run sf org open without specifying an alias.

Fix Common Salesforce DX Project Creation Errors

sf or sfdx Command Is Not Found

Confirm that Salesforce CLI is installed, restart the terminal, and verify that the CLI installation directory is included in the system PATH. Use sf --version to test the installation.

Salesforce DX Project Name or Directory Already Exists

Choose a different project name, select a different output directory, or remove the existing directory only after confirming that it does not contain work that must be preserved.

Visual Studio Code Does Not Show SFDX Project Commands

Check that Salesforce CLI and the Salesforce Extension Pack are installed. Reload Visual Studio Code after installation and open the Command Palette again. Extension commands may not load correctly when the CLI executable cannot be found.

Current Folder Is Not Recognized as a Salesforce DX Project

Run Salesforce project commands from the directory containing sfdx-project.json. If that file is missing, generate a new project or confirm that the cloned repository is actually structured as a Salesforce DX project.

Salesforce DX Project FAQs

What is a Salesforce DX project?

A Salesforce DX project is a local directory structure used to manage Salesforce metadata, configuration, source files, tests, scripts, and package definitions. Its central configuration file is sfdx-project.json.

What command creates a Salesforce DX project?

Use sf project generate --name ProjectName with the current Salesforce CLI. Older scripts may use sfdx force:project:create -n ProjectName.

How do I create a Salesforce DX project in Visual Studio Code?

Install Salesforce CLI and the Salesforce Extension Pack, open the Command Palette, and run SFDX: Create Project or SFDX: Create Project with Manifest. Then select the project name and destination folder.

What is the difference between a Salesforce DX project and a scratch org?

The Salesforce DX project is the local workspace containing source and configuration files. A scratch org is a temporary Salesforce environment that can be created from the project’s scratch definition file.

Do I need a Dev Hub to create a Salesforce DX project?

No. You can generate a local Salesforce DX project without a Dev Hub. A Dev Hub is required when you want to create and manage scratch orgs.

Salesforce DX Project Editorial QA Checklist

• Confirm that current examples use sf project generate while clearly identifying older sfdx force:project:create syntax.
• Verify that every new terminal command uses the language-bash PrismJS class.
• Check that the project directory contains sfdx-project.json, .forceignore, config, and a package directory such as force-app.
• Confirm that org authorization, Dev Hub authorization, and scratch org creation are described as separate steps.
• Verify that retrieve and deploy examples specify the intended target org and do not imply that creating a project automatically connects to Salesforce.

Creating a project in Salesforce Developer experience establishes the local workspace. The next steps depend on the development model: authorize an existing org and retrieve metadata, or authorize a Dev Hub, create a scratch org, deploy the project source, and open the org.