Local Project
A Local Project in Salesforce DX is the developer''s local folder structure that holds source-format metadata for a Salesforce org.
Definition
A Local Project in Salesforce DX is the developer''s local folder structure that holds source-format metadata for a Salesforce org. It is the workspace a developer creates with sf project generate, opens in VS Code, edits source files in, and deploys to a Salesforce org via the Salesforce CLI. The local project contains the sfdx-project.json manifest at the root, plus folders for every metadata type the developer is working with (force-app/main/default/classes, lwc, aura, objects, etc.).
The Local Project is the foundation of modern Salesforce development. Every operation flows through it: pulling metadata from an org with sf project retrieve, pushing to a scratch org with sf project deploy, version-controlling with git, running Apex tests, generating new components, and deploying to production via DevOps Center or CI pipelines. The project format follows the SFDX source format, a folder structure designed for source control and team collaboration. Salesforce moved away from the older Metadata API-format projects (the Force.com IDE-era format) in favor of SFDX source format because it works better with git, scratch orgs, and modern CI/CD.
The SFDX Local Project structure and how it works
sfdx-project.json as the root manifest
Every Local Project starts with sfdx-project.json at the root. The file declares the project name, the SFDX source-format version, the package directories (typically force-app), the default Salesforce API version, and any plug-in configuration. Salesforce CLI reads this file to understand the project structure on every command.
Source-format folder structure
Beneath force-app/main/default, the project organizes metadata by type: classes/ for Apex, lwc/ for Lightning Web Components, aura/ for Aura components, objects/ for sObject definitions, flows/ for Flow Builder flows, permissionsets/ for permission sets. Each metadata type has its own folder; each file follows the source-format naming convention. The structure is designed for git-friendly diffing.
Local Project vs. scratch org
The Local Project is the source-of-truth file system; the scratch org is the runtime environment. Developers push the Local Project to the scratch org (sf project deploy start), make changes in the org or locally, pull changes back (sf project retrieve start), and version-control the Local Project via git. Source tracking on the scratch org keeps the two in sync.
Authentication and deployment
Salesforce CLI commands operate against authenticated orgs. The developer authenticates with sf org login web, picks an org as the default (sf config set target-org=myalias), and runs commands against it. Deployments use sf project deploy start with manifest options to control which metadata pushes. Production deployments typically run from CI pipelines after pull-request approval.
Git integration as the standard
Local Projects work seamlessly with git. The folder structure is designed for branches, pull requests, and merges. Developers create feature branches, commit changes, push to GitHub or Bitbucket, and open pull requests. The SFDX format produces clean diffs at the file level, making code review straightforward.
DevOps Center and CI/CD
DevOps Center is Salesforce''s declarative CI/CD product. It reads Local Projects from a git repository, builds change sets from selected work items, and deploys them through configured environments (Dev to UAT to Prod). Third-party CI tools (Copado, AutoRabit, Gearset) provide similar functionality with more configuration depth.
Converting from Metadata API format
Legacy projects in Metadata API format (the Force.com IDE-era structure) can be converted to SFDX source format with sf project convert source. The conversion is a one-time operation; new projects should always start in source format.
Create and work with a Local Project
The basic workflow: generate the project, authenticate orgs, retrieve or deploy metadata, commit to git, iterate.
- Generate the project
Run sf project generate -n my-project. The CLI creates the folder structure with sfdx-project.json and the force-app directory.
- Authenticate against an org
Run sf org login web -a my-org-alias. The browser opens; complete the OAuth handshake. The org token is stored locally.
- Set the default org
Run sf config set target-org=my-org-alias. Subsequent commands default to this org without needing the -o flag.
- Retrieve metadata
Run sf project retrieve start to pull metadata from the org into the Local Project. Pick specific metadata types via the -m flag.
- Open in VS Code
Open the project folder in VS Code with the Salesforce Extensions Pack installed. The IDE recognizes the SFDX structure automatically.
- Edit, commit, deploy
Edit source files; commit changes via git; deploy with sf project deploy start. Iterate.
The root manifest declaring project structure.
Typically force-app, holding all metadata source files.
The command-line tool that operates against the project.
An org alias the CLI can deploy to.
Version control for the Local Project.
- Legacy Metadata API-format projects do not work with modern SFDX commands without conversion. Use sf project convert source to migrate.
- Source tracking is available only on scratch orgs and developer sandboxes. Production deployments need explicit manifest-based deploys.
- Salesforce CLI authentication is local. Loss of the developer machine means re-authenticating; tokens cannot be recovered remotely.
- The Salesforce CLI evolves quickly. Stay on the latest version to access new commands and bug fixes.
Trust & references
Cross-checked against the following references.
- Salesforce DX Developer GuideSalesforce Developers
- Salesforce CLISalesforce Developers
Straight from the source - Salesforce's reference material on Local Project.
- sfdx-project.jsonSalesforce Developers
Hands-on resources to go deeper on Local Project.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Local Project in Salesforce DX?
Q2. What goes in a local project?
Q3. What enables Git-based collaboration?
Discussion
Loading discussion…