The Salesforce Developers website will undergo maintenance on May 29, 2024 from 3:00 a.m. UTC to 10:00 a.m. UTC. The maintenance process may affect the availability of our documentation. Please plan accordingly.

Are you ready to move to Salesforce DX, but your source code is currently in a Developer Edition (DE) or Sandbox org? In this blog post, I describe the easy steps to convert existing source code to a Salesforce DX project.

I recently converted the latest version of the DreamHouse sample application to a Salesforce DX project, and I thought it would be helpful to document the process so you can use the same steps to convert your own projects to Salesforce DX. The end result for the the DreamHouse app is available in this repository, but the steps below are applicable to any project.

Step 1: Convert your project to Salesforce DX

  1. Create an unmanaged package in your existing org, and include all the assets you want to move to your Salesforce DX project. You don’t need to upload the package, and you don’t have to worry about the 75% code coverage for this purpose.
  2. If you haven’t already done so, authenticate with your hub org. Type the following command, then login with your hub org credentials and accept to provide access to Salesforce DX:
  3. Create a new Salesforce DX project:
  4. Authenticate with your developer edition org. Type the following command, then authenticate with your developer edition org credentials and accept to provide access to Salesforce DX:
  5. Export the unmanaged package metadata in a temporary directory. Type the following commands in the root folder of your Salesforce DX project:

    “mypackage” is the name of the unmanaged package you created in step 1. Afer executing this command, a file named is created in the temp directory.

  6. Unzip using a zip file management utility or from the command line. For example, on a Mac, double-click in Finder or type the following command on the command line:
  7. Convert the source code to the Salesforce DX project structure:

    You can delete the temp directory at this point.

  8. Create a scratch org:

    If you get an expired access/refresh token message, authenticate with your hub org again (step 2 above).

  9. Push the code to your scratch org:
  10. Open the scratch org:
  11. Create a permission set to provide access to your project’s assets:
    • In Setup, type permission in the quick find box, click the Permission Sets link, and click New
    • Provide a name for your permission set and click Save
    • Add the required permissions
    • Click Manage Assignments and assign the permission set to the default user (User, User)

    For example, here are the permissions I added for the DreamHouse app:

    • Assigned Apps: I added the DreamHouse app
    • Object Settings: I added all available permissions (Tab settings, Object Permissions, and Field permissions) for all the custom objects used in DreamHouse: Broker__c, Property__c, Favorite__c and Bot_Command__c.
    • Apex Class Access: I added all the classes
    • Visualforce Page Access: I added all the Visualforce pages
    • In the Find Settings box, I typed the name of all the tabs used in DreamHouse (HeatMap, HeatMap demo, Einstein Vision, and Command Center), and I enabled access (checked Visible).
  12. Pull the permission set

Step 2: Transfer sample data (Optional)

The Salesforce DX CLI also makes it easy to export sample data from your developer org and import it in your scratch orgs. It even preserves master-details relationships between records. As an example, here is how I did it for the DreamHouse app:

To export the data from my DE org, I ran the following command from the root folder of my Salesforce DX project:

After executing this command, the sample data files (Broker__cs.json, Property__cs.json, and Broker__c-Property__c-plan.json) are available in the data subfolder of my project which means that they will be part of the project when I put it under version control (step 3 below).

To import the data in my scratch org, I run the following command:

Step 3: Put your project under version control

We are done converting the project and transferring data. It’s time to put the project under version control. For example, using Github:

That’s it. It’s now easier than ever for other developers to work with you on the project. Using the migrated DreamHouse project as an example, all they have to do is:

  1. Clone the repository. For example:
  2. Create their own scratch org:
  3. Push the app to their scratch org:
  4. Assign the permission set to the default user. For example:
  5. Import data in the scratch org. For example:
  6. Open the scratch org:


Salesforce DX enables modern development workflows on the Salesforce platform. It makes team development, version control, and continuous integration easier than ever. Migrate your existing projects to Salesforce DX today using the easy steps described in this post and watch the pull requests come in!


Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS