Comprehensive SFDX Development Rules: Best Practices for Salesforce DX Projects

## 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:** ```json { "packageDirectories": [ { "path": "force-app", "default": true, "sourceApiVersion": "60.0" } ], "namespace": "", "sfdcLoginUrl": "https://login.salesforce.com", "sourceApiVersion": "60.0" } ``` **Pro Tip:** Integrate [sfdx-project-utils](https://github.com/forcedotcom/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:** ```bash sf project retrieve start --manifest package.xml --target-org dev ``` Where `package.xml` specifies: ```xml <?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](https://github.com/mshanemc/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:** ```json { "packageDirectories": [ { "path": "force-app", "default": true, "versionNumber": "1.0.0.NEXT", "definitionFile": "sfdx-project.json", "ancestorId": "04t..." } ], "name": "myProject", "namespace": "acme", "packageAliases": { "[email protected]": "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: ```bash 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:** ```json { "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:** ```markdown # 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. <div style="text-align: center; margin-top: 2rem;"> <a href="https://cursor.directory/sfdx-development-rules" target="_blank" rel="noopener noreferrer" class="view-full-resource-btn" style="display: inline-block; background-color: #f97316; color: white; padding: 12px 24px; border-radius: 8px; text-decoration: none; font-weight: 600; transition: background-color 0.2s;">View Full Resource</a> </div>