The Perfect SFDX Starter Project For Any Scratch Orgs Development

I love scratch ORGs! But setting them up can be time-consuming, so I created this template. I have found myself using this template anytime I need to create a scratch org for POC (proof-of-concept), demos, or when I need to start a new project.

This template contains all the core things that you will need in a scratch org, including scripts for setting up CI/CD. I am using GitHub Actions, but you could easily adjust it to other tools. I have been using it a lot, and I love it, so I decided to share it with you!

Once I have the base template, I import the existing metadata from a sandbox or production Org using the techniques explained in the SFDX Developer Guide | Project Setup.

I am sharing with you the repo for this base scratch org, but I want to explain some things that you will find useful.

Folders & Files

Metadata Folders: ./Deploy and ./doNotDeploy

Before I explain the contents of these folders, we need to understand there are two types of metadata in a scratch org: First, we have the metadata that we are creating or changing and that we will need to eventually deploy to sandboxes or production. The second type of metadata is the one required for the first type ;-)

Let's suppose you are building a trigger for an existing sObject. In this case, we need the metadata for the trigger itself (which will need to deploy), but we also need the metadata for the sObject, fields, page layouts, list views, profiles, permission sets, etc (which we do not want to deploy). When it's time to deploy all our work back to a sandbox or production server, we need to easily identify the metadata, but with this sturucture is quite easy becase it's located in the ./deploy folder. All the other metadata that is needed to build the code, but that won't be deployed, is stored in the ./doNotDeploy folder.

To make this work, we need to work with the ./sfdx-project.json file. This file tells SFDX how the metadata is organized, in particular, this setting:

"packageDirectories": [
	{
		"path": "doNotDeploy",
		"default": false
	},
	{
		"path": "deploy",
		"default": true
	}
]

Both folders get processed when pushing metadata to a scratch org. When doing a pull, SFDX puts the new metadata in the default (./deploy) folder.

Code Formatting (./.prettierrc)

The ./.prettierrc file indicates how the code gets formatted. It specifies the maximum with for the code, and that we will be using tabs vs. spaces. I prefer tabs over spaces, but let's not pick up a fight over that!

./config/project-scratch-def.json

This file describes the definition of the scratch org that gets created. There are few things of interest here:

hasSampleData: false

If true, then sample data will be created. But I also learned that sample metadata gets also created, so be careful. There are custom fields that get created on standard objects like accounts, leads, etc which you may not want.

settings.mobileSettings.enableS1EncryptedStoragePref2: false

Setting this flag to false (highly recommended for scratch orgs), the orgs will not use the cache for UI rendering. There is a checkbox is the setup menu (Security | Session Settings | Caching) called Enable secure and persistent browser caching to improve performance which users love to have checked, but developers want to have this unchecked! This setting sets it while creating the scratch org.

./.vscode/tasks.json

This file helps to push metadata by using the VS Code pre-defined builder. When the build operation starts (⌘⇧B), VS Code saves unsaved, and it executes the commands defined in this file. In our case, the metadata gets pushed to the scratch org.

./@ELTOROIT Folder

This folder contains two crucial pieces of a successful scratch org creation:

• The data to populate a scratch org
• The scripts to create the scratch org

Creating the scratch Org (./@ELTOROIT/scripts/shell/CreateOrg.sh)

This batch files executes the common tasks that need to be done when creating a scratch org, they are:

Footnotes

1: These switches are configured on the CreateOrg.sh file

2: Before the scratch org is created and the metadata/data is loaded, the Jest tests are executed.

3: Helps accessing the previous scratch org easily. Althought SFDX does not remove the old scratch org, it drops the alias and it's hard to recognize the previous org when one gets created.

4: I have noticed that sometimes the orgs that get created do not get the My Domain adequately configured, and trying to open the scratch org does not work and takes you over to the standard login screen. This optional step opens the scratch Org and pauses the script until you verify the new scratch org opens and hit the enter key.

5: There are actually two variables used here. The switch SHOW_DEPLOY_PAGE controls if the deploy status page is opened or not, and DEPLOY_PAGE is the URL for the actual page to open. This last one is set in functions.sh.

6: This allows you to monitor the installation progress

7: This opens a specific URL to allow you configuring manually something that can't be saved as metadata. Sometimes, you need to perform some manual configuration (the configuration does not have corresponding metadata) on the scratch org before (or after) the metadata is pushed to the org. These settings pause the creation of the org and let you perform that manual configuration before continuing with the creation of the org.

8: Some configuration does not map to a metadata file. Still, we can code them in Apex, and we can execute that Apex while creating the scratch org in this optional step. Maybe this is because the Apex code needs to be done once the metadata is loaded (assigning profiles, roles, ...) or after the data is loaded.

9: This is a list of package Ids to be installed. The switch must be set as a shell array like this: PACKAGES=("04tB0000000P1yA" "04tB0000000P1yB" "04tB0000000P1yC")

10: Hides the standard applications on the App Launcher, making it easier to work with your scratch org if you are creatina a custom app or even working with a standard app.

11: I am using ETCopyData to load data. We may have very complex data structures that are not easily loaded with the core SFDX commands provided. This repo uses the ETCopyData plugin I built. You can find it here: https://github.com/eltoroit/ETCopyData

12: This is useful if you are doing a CI/CD because the Apex tests run when the scratch org is created.

13: I have seen in the latest CLI that conflicts do occur the first times the metadata gets pushed, pushing the metadata here helps "prevent" that.

14: Sometimes, for example, if you want to use the Salesforce Mobile App or connect via APIs, you may need the username/password for the org. This last optional step generates that password.

As indicated in the table above, not all these operations are required, and they can be customized based on the variables at the CreateOrg.sh script. You could also invoke each of these commands separately ./@ELTOROIT/scripts/shell/CreateOrg.sh mainRunJest

The separation helps when you configure a CI/CD tool, I am using GitHub Actions and this is what my YAML file looks like:

name: "ELTOROIT Test Scratch Org"
on: [push]
jobs:
    create_org:
        runs-on: ubuntu-latest
        env:
            ET_CICD: true
        steps:
            - uses: actions/checkout@v2
            - name: Create etLogs folder as needed
              run: mkdir -p etLogs
            - name: PWD
              run: pwd
              if: ${{ env.ET_CICD  }}
            - name: Export token
              run: echo ${{ secrets.DEVHUB_TOKEN}} > etLogs/token.txt
            - name: Install tools
              run: |
                  wget https://developer.salesforce.com/media/salesforce-cli/sfdx-linux-amd64.tar.xz
                  mkdir sfdx-cli
                  tar xJf sfdx-linux-amd64.tar.xz -C sfdx-cli --strip-components 1
                  ./sfdx-cli/install
                  sfdx force:lightning:lwc:test:setup
                  echo 'y' | sfdx plugins:install etcopydata@beta
            - name: Register DevHub
              run: sfdx force:auth:sfdxurl:store -f etLogs/token.txt --setalias DevHub --setdefaultdevhubusername
            - name: Run Jest
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainRunJest
            - name: Create Scratch Org
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainCreateScratchOrg
            - name: Open deploy page
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainOpenDeployPage
            - name: Execute Apex Before Deployment
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainExecuteApexBeforePush
            - name: Install Packages
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainInstallPackages
            - name: Deploy Metadata
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainDeploy
            - name: Execute Apex After Deployment
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainExecuteApexAfterPush
            - name: Assign Permission Set
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainAssignPermissionSet
            - name: Deply Admin Profile
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainDeplyAdminProfile
            - name: Load Data
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainLoadData
            - name: Execute Apex After Data
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainExecuteApexAfterData
            - name: Generate Password
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainGeneratePassword
            - name: Run Apex Tests
              run: ./@ELTOROIT/scripts/shell/CreateOrg.sh mainRunApexTests

Bonus content

./@ELTOROIT/scripts/DeleteOrgs.sh

One of the things I like to do with scratch Orgs is to create more scratch orgs than needed. This process helps me know the metadata I have in the repo is complete, and that I will be able to create a scratch org at any time. It also helps me prove the demos I am sharing with the world can work. This creates a ton of scratch Orgs, that need to be cleaned!

This script looks for scratch orgs that do not have an alias associated (I may have re-used the alias with a new scratch org) and deletes them.

Warning: I am a Mac developer, and this script was created and tested on a Mac and Linux (GitHub Actions and Salesforce Code Builder). I believe that it could be easily executed on Windows 10 using WSL.