Setting up a Salesforce DX project means installing the CLI, authenticating the Dev Hub, scaffolding the project, creating a scratch org, deploying source, and running tests. The first run takes an hour. Every subsequent run takes minutes.
- Install the Salesforce CLI
Download the installer from developer.salesforce.com or npm install -g @salesforce/cli. Confirm with sf --version. The CLI auto-updates by default, so no version management is required.
- Enable Dev Hub on the target org
Log into the production or developer-edition org. Setup, Dev Hub, Enable Dev Hub. Save. Without this, the org cannot mint scratch orgs.
- Authenticate the CLI to the Dev Hub
Run sf org login web --alias DevHub --set-default-dev-hub. A browser opens, you log in, the CLI stores the OAuth token locally. Future commands reference the alias instead of re-authenticating.
- Scaffold a new DX project
Run sf project generate --name MyProject. The CLI creates the standard folder structure: force-app/main/default for source, config/project-scratch-def.json for scratch org definitions, sfdx-project.json for package configuration.
- Create a scratch org
Run sf org create scratch --definition-file config/project-scratch-def.json --alias mywork --set-default. The Dev Hub validates and provisions the org in 2 to 5 minutes. The alias is what subsequent CLI commands target.
- Push the source
Run sf project deploy start to push the current local source to the scratch org. The CLI tracks file changes and only sends what is new. For larger projects, sf project deploy start --source-dir force-app/main/default/lwc deploys a subset.
- Run Apex tests
Run sf apex run test --result-format human to execute all tests. Add --code-coverage for the coverage report. CI pipelines use --result-format junit to feed test results into the build system.
The parent org that mints scratch orgs. Enabled once per company in Setup. Production orgs can be Dev Hubs with no additional license cost.
JSON file in config/ that declares the edition, features, language, and preview release for the scratch org. Variants per use case (qa, integration, perf) are common.
The DX folder layout for metadata. The CLI converts to/from metadata format automatically when deploying through legacy paths.
The project manifest that declares package directories, the default package, and the namespace if the org is a managed-package developer.
The 2GP package type for modularizing metadata. Built from source, versioned, and installable into any org without a release branch.
Variant that skips ancestor validation, useful for customer-specific packages that depend on existing org metadata.
- Scratch orgs do not inherit sandbox data. Every scratch org starts empty. Seed data through sf data tree import or a custom Apex script for any test that requires populated records.
- Source format and metadata format are not interchangeable in git. The repository should commit one or the other, not both. The DX convention is source format.
- Dev Hub limits cap how many scratch orgs you can spin up per day and keep active. Enterprise Dev Hubs allow more, but the limit catches small teams off guard.
- Unlocked packages bind to a namespace. Once installed, the namespace prefix appears on all components from that package. Plan namespaces before publishing a package to production.
- The CLI auto-updates by default. Pin the version in CI (sf-plugins-core, JIT updates disabled) for build reproducibility.