Quick Notes: Getting started with SalesforceDX

Published in

Taming The Force

4 min readMay 1, 2019

This isn’t anything new and all steps can be found online already. This just helps me to solidify my understanding and ensure that I have all the steps on lock down.

Step 1: Create a Project

The first step is to create the project which is the base folder from which the work will be done.

sfdx force:project:create -n MyProjectName

-n is the parameter to the name of the project.

The command creates the folder structure that is required with the root folder being the name of the project. It’s helpful to change directory (cd) into the folder. In which case:

cd MyProjectName

Step 2: Authorise the Dev Hub

Next, we’ll need to have an org that allows us to create and manage scratch orgs.

sfdx force:auth:web:login -a MyDevHubName

-a is the parameter for the alias of the Dev Hub. This is typically set to “DevHub” but can be any name

If the org hasn’t been enabled, then go to Setup -> Development -> Dev Hub and click the toggle to enable it.

Step 3: Create a scratch org

The scratch org is where we make changes, similar to how we would use a sandbox to make changes.

sfdx force:org:create -a MyScratchAlias -f config/project-scratch-def.json

The benefit to scratch orgs is that with source tracking means that changes are automatically tracked¹.

Step 4: Push from the source to the scratch org

Push the basic metadata from your Dev Hub to your scratch org². This makes sure that the scratch org has the same basic configuration as your Dev Hub so that you are in a position to make the changes you need.

sfdx force:source:push -u MyScratchAlias

-u is the parameter for the alias of the target org. When a scratch org is created (step 3), it becomes the default target, however, this just makes it easier for learning and keeping track of what is going on.

Step 5: Make your changes

Make changes to the org¹.

Step 6: Pull your changes

This brings your changes¹ back from the scratch org into your project so that you can deploy them from one org to another.

sfdx force:source:pull -u MyScratchAlias

-u, same as before, is the parameter for the alias of the target org.

Step 7: Test your changes

Check that the changes you have made have been successfully tracked and are in your project. Do this by creating a scratch org and pushing from your source to that new scratch org (steps 3 and 4).

sfdx force:org:create -a MyScratchAlias2 -f config/project-scratch-def.jsonsfdx force:source:push -u MyScratchAlias2

Step 8: Convert from Source format to Metadata API format

Possibly the trickiest step. The problem with source format is when you try to push to the target, it will compile what it’s able to and ignore any errors. This means that you could get a partial deployment if you have any errors.

To get around this, it’s best to use the metadata api to deploy changes because it will rollback if there are any errors.

In preparation, there should be a target folder where the project, in its new format, will be stored. This can still be in the same project so for convenience just make a directory (mkdir) in the project folder.

mkdir MyConvertedProject

Now we can run the conversion to convert the project’s source into metadata format.

sfdx force:mdapi:convert -r MyProjectName -d MyConvertedProject

-r is the root directory of the project
-d is the target directory for the converted files

Step 9: Deploy changes

The metadata API deploys zip files so the converted project must first be converted before it can be deployed.

This conversion can be done via the command line or manually.

zip -r -X MyZipFileName.zip MyConvertedProject

-r zips the target directory as well as all
-X prevents the funky “_MACOSX” and other such files from being added to the zip file³. This is important because those funky files would causes errors when deploying.

Once converted, deploy the zip file.

sfdx force:mdapi:deploy -f MyZipFileName.zip -l RunLocalTests -u MyDevHubName -w 10

-f is the parameter for the path to the zip file
-l specifies the level of tests that should be run
-u, again, specifies the username of the target. This is not necessary as the default is likely the DevHub that’s been setup. However, it doesn’t hurt to be sure!
-w specifies, in minutes, how long the wait time for the command to finish

[1] Not all changes are tracked. Use the metadata coverage report to determine whether your changes are tracked or not.

[2] There are limits to the number of scratch orgs that can be created and active at a single point in time. Check the developer guide for some factors to consider.

[3] Case is important. “-X” command prevents the other files from being added while “-x” excludes particular file names.