SalesforceDX: Getting Started With Existing Code

So the promise of Dreamforce 2016 is slowly but surely being fulfilled. I've still only had limited experience with SalesforceDX so far, but what I have seen of it is definitely exciting, and it's already making life for developers easier. There's plenty of road left to travel, but now is a good time to start getting acquainted with these new tools (the sfdx command line program in particular) so that you know what's available and whether it's something you can start to use in anger.

A lot of the documentation I've seen so far seems to revolve around creating a project from scratch; that's great, but not necessarily realistic. For a lot of us "new" projects are few and far between, but we have more than a few existing code bases to work with.

The Basic Recipe

This is a simple set of steps that should get you going if you've got some existing code and customisations that you want to get out of the old model and into the promised land where version control is the source of truth. The basic gist to grab your existing metadata, convert it to the new format, and chuck it into source control. The steps below assume you've installed the SalesforceDX CLI and hooked it up to your dev hub.

1. Create an unmanaged package in the source org with everything you need in it. This is optional if you have an existing package.xml that you can use, but this is an easy way to create one.

2. Create a new, empty, SFDX project:
   sfdx force:project:create --projectname projectMayhem

3. Authenticate with the existing org where you created the package, and give it a friendly name:
   sfdx force:auth:web:login -a SourceOrg -s

4. Retrieve the existing metadata for your unmanaged package (called projectMayhem here):
   sfdx force:mdapi:retrieve -p projectMayhem -r ./package_src

5. Unzip the package:
   e.g. unzip ./package_src/unpackaged.zip

6. Convert the metadata into the new SFDX project format:
   sfdx force:mdapi:convert -r ./package_src/projectMayhem

At this point you've made it to the new world. You should have everything in the new project which means you can go ahead and check it out in a shiny new scratch org:

sfdx force:org:create -s -f ./config/project-scratch-def.json
sfdx force:source:push
sfdx force:org:open

If you need a specific edition of Salesforce, or to turn on features like multi-currency, you'll need to edit the project-scratch-def.json file first, there's a list of options available in the documentation.

Assuming everything looks good you can now throw this new project into a version control repository and start a new, happy life.

Use The Help!

Obviously the above isn't exhaustive, and there are further steps if you want to grab some data for loading into scratch orgs and the like, but the idea here was to get you up and running quickly with the most basic parts. Remember that you can get plenty of help from the sfdx program itself, sfdx help is your friend, and works for different levels of the command hierarchy, e.g. sfdx help gives a list of the top level commands, sfdx help force shows the next level down, and so on, all the way down to specifics for something like sfdx help force:apex:execute.