Comprehensive SFDX Development Rules: Best Practices for Salesforce DX Projects

Master Salesforce DX with these essential development rules. Ensure scalable, standardized projects using source format, proper naming, and optimized structures for efficient CI/CD pipelines.

Core Principles for SFDX Development

Salesforce DX (SFDX) revolutionizes Salesforce development by enabling source-driven workflows, version control integration, and modular project structures. Adhering to strict rules ensures consistency across teams, reduces deployment errors, and facilitates scalable org-based development. These guidelines draw from industry standards and tools like the Salesforce CLI, providing a blueprint for professional SFDX projects.

Rule 1: Always Use Source Format

Mandate the use of source format over metadata format in all SFDX projects. Source format breaks down metadata into granular, human-readable files, making it ideal for version control systems like Git. This approach supports selective deployments, easier diffs, and precise conflict resolution.

Why it matters: Metadata format bundles components into opaque ZIP files, hindering collaboration. Source format aligns with modern DevOps practices, enabling features like scratch orgs and package development.

Implementation steps:

• Initialize projects with sf project generate -n myProject --manifest and ensure sourceApiVersion is set in sfdx-project.json.
• Convert existing metadata using sf project retrieve start -m CustomObject:Account.

Example project setup:

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

Pro Tip: Integrate sfdx-project-utils to validate and enforce source format compliance in CI pipelines.

Rule 2: Standardize Project Structure

Enforce a uniform directory layout: force-app/main/default/ for all metadata. This mirrors unlocked package conventions and simplifies scaling to second-generation packaging.

Deep Dive: Subfolders include classes/, triggers/, aura/, lwc/, objects/, pages/, staticresources/, etc. Avoid custom paths to prevent retrieval/deploy issues.

Real-world application: In enterprise teams, this structure enables parallel development streams. For instance, separate force-app/test/ for test classes if needed, but keep production code in main/default/.

Code Snippet for Validation:

sf project retrieve start --manifest package.xml --target-org dev

Where package.xml specifies:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>MyClass</members>
        <name>ApexClass</name>
    </types>
</Package>

Rule 3: Adopt Strict Naming Conventions

Use PascalCase for Apex classes, triggers, LWCs, Aura components, and custom objects. Custom fields and labels follow CustomField__c and Label_Name. Profiles and permission sets use ProfileName__Profile and PermissionSetName__PermSet.

Rationale: Consistent naming prevents collisions, aids discoverability, and aligns with Salesforce's conventions. It also supports automated tools for scanning and refactoring.

Examples:

• Apex Class: AccountService
• Trigger: AccountTrigger
• LWC: accountList
• Custom Field: Preferred_Contact__c

Enforcement: Leverage ESLint plugins or pre-commit hooks with salesforce-cli-schema for schema validation.

Rule 4: Configure sfdx-project.json Precisely

Every project must have a valid sfdx-project.json at the root. Key properties: packageDirectories with path, default, versionNumber (for packages), ancestorId, definitionFile. Set namespace if applicable.

Advanced Configuration:

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true,
      "versionNumber": "1.0.0.NEXT",
      "definitionFile": "sfdx-project.json",
      "ancestorId": "04t..."
    }
  ],
  "name": "myProject",
  "namespace": "acme",
  "packageAliases": {
    "MyPackage@1.0.0-0": "04t..."
  }
}

Benefits: Enables package versioning, dependency management, and scratch org creation via sf org create scratch --definition-file project-scratch-def.json.

Rule 5: Leverage Manifest Files Effectively

Use package.xml for retrieves/deploys, .package-meta for packages. Include only necessary metadata to minimize bundle size and deployment times.

Best Practice: Generate manifests dynamically:

sf project retrieve start -m "ApexClass:AccountService" -o prod

Pitfalls to Avoid: Wildcards like <members>*</members> can retrieve excessive metadata, bloating repos.

Rule 6: Optimize for Scratch Orgs

Define scratch orgs with project-scratch-def.json specifying orgName, edition, features[], settings. Use unique suffixes for aliases.

Example:

{
  "orgName": "My Dev Org",
  "edition": "Developer",
  "features": ["EnableTestCoverage"],
  "settings": {
    "orgPreferenceSettings": {
      "S1EncryptedStorage": true
    }
  }
}

Workflow: sf org create scratch -f config/project-scratch-def.json -a my-scratch → Push source → Run tests → Delete.

Rule 7: Enforce Testing and Coverage Standards

Achieve 75%+ coverage. Place tests in force-app/test/ or same folder with @isTest. Use sf test run apex --tests TestClassName --wait 10.

CI/CD Integration: Hook into Jenkins/GitHub Actions for automated runs.

Rule 8: Version Control Best Practices

.gitignore Salesforce artifacts like .sfdx/, local/, build/. Commit sfdx-project.json, manifests, and source only.

Branching Strategy: Feature branches from main, PRs with validation.

Rule 9: Documentation and Readme

Include README.md with setup instructions, deployment scripts, and org shapes.

Template Snippet:

# My SFDX Project

## Setup
1. `sf org login web -a dev`
2. `sf project retrieve start -x manifest/package.xml`

Rule 10: Tooling and Automation

Use VS Code with Salesforce Extensions. Integrate Husky for pre-commit linting. Monitor with sf org list and sf data export.

Scaling Tip: For monorepos, use multiple packageDirectories with distinct paths.

These rules form a robust foundation, adaptable for solo devs to large teams. Implementing them reduces technical debt and accelerates delivery in Salesforce ecosystems.