A DX Project starts with sf project generate. From there, customize the structure for your team, connect to a Dev Hub, and commit to Git. The first 30 minutes set the foundation for years of source-driven development.
- Generate the project
From your work directory, run sf project generate --name MyProject. The CLI creates a MyProject directory with the standard layout: force-app/main/default, config, manifest, sfdx-project.json.
- Initialize a Git repository
cd MyProject, then git init. Salesforce DX projects belong in version control from day one. Treat .sfdx as gitignored (the project generator includes a .gitignore by default).
- Authenticate the CLI against a Dev Hub
Run sf org login web --alias DevHub --set-default-dev-hub. The CLI authorizes against your Dev Hub for scratch-org creation.
- Retrieve initial metadata from an org
To start from existing org content, run sf project retrieve start --source-org existing-org-alias. The retrieve writes metadata into force-app/main/default. Commit and move on.
- Customize the project for your team
Edit sfdx-project.json: set the sourceApiVersion, add packageDirectories if you have multiple sub-packages, set namespace if building a managed package. Update config/project-scratch-def.json with the org shape your team needs.
- Commit and push to a remote
git add then git commit -m Initial DX project. Push to GitHub, GitLab, or whichever remote you use. The project is now ready for collaborative development.
One packageDirectory at force-app, basic config and manifest. The starting point for most projects.
Multiple packageDirectories for separate 2GP or unlocked packages. Used when shipping reusable features.
Multiple scratch-org definition files for different feature sets (basic dev, Industries-enabled, Service Cloud Voice-enabled).
Add .github/workflows/ci.yml (or equivalent) to wire the CLI into pull-request automation.
- The sourceApiVersion in sfdx-project.json controls what API version metadata is retrieved against. Drift between this and your org''s release version creates deployment surprises; keep it current.
- Scratch-org definition files are not free-form. The fields are documented in the Scratch Org Definition Reference; typos or invalid feature names fail org creation with cryptic errors.
- Multi-package projects require disciplined dependency management. A package that depends on another must declare the dependency in sfdx-project.json''s packageDirectories; otherwise installs fail.
- Source tracking only works for orgs that support it (scratch orgs and Dev Hub-tracked sandboxes). Older sandboxes need explicit deploy/retrieve operations.