Deploying metadata in Salesforce is a crucial part of the development process as it enables developers to move customizations and code from their local environment to various Salesforce orgs. Whether you're working in a sandbox, a CI/CD environment, or directly within production, understanding how to efficiently and accurately deploy your changes is key to maintaining a smooth development workflow.

‍

In this guide, we'll explore the various methods Salesforce developers can use to deploy metadata using Visual Studio Code and the Salesforce CLI. From simple deployments of individual Apex classes to managing complex, multi-org environments, this guide will help you leverage these tools to streamline your development process.

‍

‍

Deploying Metadata From Visual Studio Code to a Salesforce Org

We’ll begin inside an SFDX project, and you’ll also see in the examples that we’re connected to our CI/CD dev org. 

‍

Since deployment from an SFDX project to a Salesforce org is a typical development workflow, when we’re modifying Apex classes or Apex triggers we’ll do it locally within an SFDX project and then deploy the changes to our developer sandbox. Note that this differs from the previous method where we would potentially use the developer console directly in that Salesforce org.

‍

To give that a try, let’s add a tiny comment in one of the classes and then save.

‍

How to Compare Metadata

Having added that comment and saved, let’s look first at a particularly useful SFDX feature before we deploy. If we right click the file, we’ll see an option called “Diff File Against Org”. This feature will check how the local file in our computer differs from the org that the project is connected to.

‍

‍

Now we can see the differences side by side. On the left side, we see what’s in the org, and on the right side, we see what’s currently local in our SFDX project. This is reflected in the header, where we see our username on the left (representing the org) and “local” on the right. This is why the comment we just added is shown in green with plus signs marking the rows—to show that these lines are an addition that doesn’t appear in the org. 

‍

‍

There are a few different use cases for this feature. For example, maybe you’ve been developing for a while in an Apex class and, although you’re not using Git, you can still make changes in the Apex class locally. In this case, if you forget which parts you added or which parts are not yet deployed to the Salesforce org, you can run a diff (i.e. use the “Diff File Against Org” feature) and see exactly what’s local and what’s in the org.

‍

Another time you might want to use this feature is when you’re using a shared sandbox that many others are using at the same time (although we don’t recommend shared sandboxes). If you want to work on an Apex class, you may want to run a diff before you deploy your changes in order to see if anyone has made any changes in the org. If you deploy without checking, your changes will overwrite what someone else is doing in the org. This particular method is a poor man’s continuous integration as this whole process should be automated, but it’s something to be aware of in case you find yourself in such a situation.

‍

Closing the diff, let’s deploy our changes to the Salesforce org. We’ll right click our file, and this time click “Deploy This Source to Org”. Once the changes have been deployed, we’ll run the diff again and make sure that what’s in our project is exactly the same as what’s in the org.

How to Automatically Deploy Changes

If you’re writing a lot of Apex, it can get pretty old to right click and hit “Deploy This Source to Org” over and over. Wouldn’t it be easier if you could have that action automated, so that every time you click save (or hit Cmd + S) your changes are deployed to the org? Well, good news! There’s an option in SFDX to do exactly that: Deploy on Save.

‍

To find out how to enable this feature, let’s first do a quick Google search for “SFDX Deploy on Save”, which will bring up the instructions we need. According to the documentation, we’ll have to modify one of our files in the SFDX project. You can see the instructions below or do your own Google search to find them.

‍

‍

Once we make those changes in our SFDX project, we’ll be able to simply hit save and have our changes automatically deployed to the Salesforce org to which the project is connected.

‍

How to Deploy with CLI

There are a few other ways to deploy to the Salesforce org your project is connected to. For example, we can right click on the file from within the file explorer and hit “Deploy Source to Org”.

‍

‍

We can also deploy all the classes, so if we’ve made changes to many different classes we can do that all at once. We’ll just right click on the class folder in the file explorer and click “deploy”. 

‍

The reason we are able to deploy just one class, the entire class folder, or any other folder, is because this is using SFDX or the Salesforce CLI behind the scenes. If we look at the command for deploying, we’ll see we can specify a folder or item to deploy rather than just saying “deploy all”. Let’s look at how to do that manually.

‍

In the terminal, we’ll type in the following command and then, when we hit tab, we’ll see below it the various directories we could deploy.

‍

‍

For example, we could deploy the entire force-app directory, or we could just deploy the Apex classes by using the following command:

‍

‍

This is exactly the same thing we did earlier by right clicking the “classes” folder and hitting deploy.

‍

We could also deploy one individual Apex class. Let’s search for a class using that same command just above; for our example we’ll search for one starting with “te” to find a test. The results will appear below.

‍

‍

Once we choose one, we’ll type that in (this is easier if you’re using autocomplete) and hit enter. This will only deploy that specific Apex class, which gives us the same result as if we had right clicked the class in the file explorer or if we had right clicked the class inside the open file and hit deploy.

‍

The recommended developer workflow is to use Visual Studio Code and the Salesforce CLI together with extensions to do your normal day to day development. You’ll first do the development locally and then deploy to your personal or development sandbox.

Using SFDX to Deploy from Org to Org

SFDX can also be used to deploy from one org to another. Until now, we’ve been looking at how to deploy from your local SFDX project to your development sandbox. However, you may also want to deploy from your development sandbox to UAT, integration, or even production. We’ll see shortly how to automate that end to end, but first, let’s walk through how to do it manually using SFDX in case the need arises. To do that, we’ll use an SFDX project as a container of metadata to deploy from one org to another. It doesn’t have to represent an entire org like what we’ve seen so far.

‍

To start, let’s create a new project in Visual Studio Code using “Create Project With Manifest”. We’ll choose a standard template, give the project a name (e.g. org-to-org), and then connect it to our developer sandbox.

‍

Having already created a custom field in our developer sandbox, we’ll now create an Apex class in Visual Studio Code and then deploy both the field and the Apex class to a completely new org. In Visual Studio Code, click Cmd + Shift + P and then “Create Apex Class.” We’ll call this “OrgToOrg”.

‍

‍

‍

This may look a little weird because we currently have a project with only one class and everything else is empty, but that’s exactly it—for this purpose, we don’t have to have an SFDX project that has all our metadata. We only need that when we’re wanting to implement CI/CD or when we want to store our project in version control. But, if we just want to do simple deployments from org A to org B, we can simply use the project as a container. It doesn’t matter if the folders are empty.

‍

So, how do we deploy this to another org? We can just change the default username to point to the target org and then run an SFDX deploy command. In this case, it doesn’t matter that the metadata came from a different org; it’ll just be deployed to whatever org we choose.

‍

Before we deploy, we’ll need to retrieve that custom field because our new project doesn’t have it. We’ll get an error because this custom field (shown in the below image) doesn’t exist. That is, it exists in the development sandbox, but it doesn’t exist in the project. In a normal project, we may already have that field, but since this is a small project we’re only using as a container to deploy a subset of metadata from one org to another, we don’t have that field.

‍

‍

To retrieve that field into this project, we’ll first switch back to our development sandbox and then use the following command (with “m” standing for “metadata”).

‍

‍

Our SFDX project now looks a bit like a chain set. It only has what we want to deploy to the other org. Again, it doesn’t matter that the folders are here and empty. SFDX will only take care of deploying what’s in the container.

‍

Switching back to the sandbox we want to deploy this to, we’ll now deploy the entire force-app folder. Normally in an SFDX project, this isn’t something we’d want to do because it will deploy everything, but in this case “everything” is just a subset of metadata.

‍

Now when we move to our target org, we’ll see that the metadata has been deployed. This is really nice because we were able to use an SFDX project as a chain set or as a container for the metadata we wanted to deploy. The important thing to remember is that an SFDX project doesn’t have to represent the entire metadata of an org. You can choose which metadata you want to include and then change the default username to deploy that to any other org you want.

Deploying Source Packages

Although it’s not technically an official term, “source packages” are packages that are not really packages in the sense that they’re not unlocked, work-dependent, or managed packages. Instead, they are packages defined at the source (i.e. SFDX project) level. Let’s take a look at an example.

‍

For this example, we’ll use an SFDX project that already has a lot of Apex classes and packages inside one folder. The concept of “source packages” is the ability to segment this folder into subfolders where every subfolder will have classes of a specific domain. 

‍

In the Salesforce world, before unlocked packages became common, we used to segment our Apex classes by using a prefix such as “account” or “batch”. This was done because there was no way to segment code in a package-based style like we can now do with unlocked pages. However, with the method we’re looking at now, we can get the benefits of packages without actually using packages.

‍

As you can see in the image below, we’ve already written a JavaScript file that will go over all the Apex classes in the default directory to see if there is a prefix. The prefix will be a typical prefix, ending with _className.

‍

‍

Let’s run that using Node.js. If the prefix we specified is found, the script will start creating folders of those prefixes and then do the same for test classes. If it finds that there are test classes, it’ll also create a folder to put the test classes in. This will allow us to have a better segmentation of our Apex classes.

‍

Now we can see that our class folder has been organized into smaller packages. As you can see in the following image, we’ve got a financial force package and an SRM package, etc.

‍

‍

Within each package, we have the source, which is the actual classes, and the tests, which is the test classes. 

‍

‍

Since the Salesforce CLI allows us to deploy a specific folder, if we’re implementing CI/CD later on and make a change only to the financial force library, we can specify in our pipeline that we only want to deploy that source package. We won’t want to deploy everything else in the org because it may not all be relevant.

‍

One way we could do that is by using the following command, using the path to say we’re going to deploy that specific path:

‍

‍

This feature of SFDX gives us the ability to have completely random, arbitrary folders and still have the ability to deploy those as if it were a normal deployment. This is very powerful and something to be aware of.

Deleting Metadata

We can also use SFDX to delete metadata. Deleting metadata is basically a deployment, but instead of adding or modifying a piece of metadata we’re just deleting it from the org. 

‍

Since the SFDX or the Salesforce CLI is using the metadata API behind the scenes, let’s start by taking a look at that documentation so we can become familiar with what’s going on and troubleshoot issues easily if they occur.

‍

‍

Deleting metadata with the metadata API is a bit odd as we have to have two XML files. One has to be called destructivechanges.xml and it has to contain the metadata that we want to delete. We’ll also need an empty package.xml. These need to be in the same folder, and then we’ll deploy the entire folder.

‍

‍

With SFDX, there is a delete command that allows us to delete metadata much more easily. However, let’s first look at the old version since we may still see it in the field and it’s important to be aware of.

‍

In Visual Studio Code, we can see that we’ve already created a folder named “itemsToDelete”. 

‍

‍

We want to delete the Apex class that we created earlier, OrgToOrg, so we’ve specified that in the destructiveChanges.xml (first image below). We also have a package.xml, which is empty except for the API version (second image).

‍

‍

‍

We’ll now use the actual metadata API—not the source commands—and specify that we want to deploy everything in the “itemsToDelete” folder. Deploying the folder then deploys the destructive changes and, behind the scenes, Salesforce realizes that it’s a deletion and deletes the Apex class.

‍

To do that, we’ll run the following command:

‍

‍

Since we’re using the metadata API directly (and not the source commands), this doesn’t give us the results right away. To see those results, we’ll need to run another command with the deployment ID.

‍

‍

Once we see that the command succeeded, we can double check that in the org. We should see that the Apex class is no longer there.

‍

Let’s now look at how we would do this using the newer SFDX commands. For this example, we’ve moved our same Apex class over to a folder named “deployAndDelete.” We’ll go ahead and run the following command:

‍

‍

We should get a confirmation that this will delete these two files from our computer and from the org. Since we want to proceed, we’ll hit “yes”. And there we go—it’s been deleted.

‍

Looking again at our metadata API documentation, there’s a section that explains how to delete metadata before we add or update an existing component. 

‍

‍

The typical example of this (which is shown in the documentation) is if you have an Apex class that references a custom field or a custom object and you want to delete the custom object. You can’t delete the custom object unless you delete the Apex class first, or unless you comment out the code from the Apex class so that it doesn't reference the object anymore. In this case, you can specify two packages: one package.xml with the class you’re going to update to remove the reference and a destructiveChangesPost, which will contain the metadata that you want to delete after the package.xml is deployed.

‍

This method is a bit complicated and potentially no longer needed as we now have the source:delete command. We could perform a deletion first and then run a deployment, or we could just do a deploy and then delete. However, it is important to know that the deploy command does have the flags to specify --predestructivechanges or --postdestructivechanges. The documentation provides examples of how to do both. 

‍

These are important to be aware of as you may see them in other implementations and there may be scenarios where they are still useful. Our recommendation, however, is to use the delete command first and then deploy, or switch the order if that works better for you.

In Conclusion

In this guide, we examined the various methods available for metadata deployment using Visual Studio Code and the Salesforce CLI. Knowing how to compare metadata, execute both manual and automated deployments, delete unwanted components, and manage org-to-org transfers is hugely beneficial for any Salesforce developer aiming to improve efficiency and accuracy when moving customizations between environments.