We're starting to figure out Unlocked Packages in Salesforce DX, and finally have a working base version. However, we do plan on breaking out fields, classes, etc to dependent packages as we continue to work.

Is there a process that allows us to safely move a piece of metadata from a package to one of its dependent packages? Since I may have already screwed up with the upload (assuming I can't safely move fields), what should I do with the existing Unlocked Package I created? As far as I can tell, we can't delete or modify versions of a package at this time.

The documentation does not seem to be clear on how to do any of this, and I would rather not install a package that will later delete a bunch of custom fields if I make a mistake.

Edit: Also, can we move metadata from a dependent package to a base package as well? This may also become necessary as I continue to build out packages in DX.

  • 1
    Have you posted to the Unlocked Package group ? The PMs are usually very responsive: success.salesforce.com/_ui/core/chatter/groups/… Or happy to post on your behalf if that is quicker/easier? Aug 6, 2019 at 20:10
  • @BritishBoyinDC Honestly, I've a lot on my plate at the moment, I would greatly appreciate the help. I'd rather not miss the answer, as it'll become important sooner than later.
    – sfdcfox
    Aug 7, 2019 at 0:06
  • 2
    sfdcfox still has Salesforce questions himself? That gives the rest of us hope to keep plugging away :-) Aug 7, 2019 at 13:48
  • @sfdcfox - did you still want me to post to the Success Group, or do these answers have you covered? Aug 7, 2019 at 19:39
  • 1
    @BritishBoyinDC Got what I needed to know.Thanks for following up!
    – sfdcfox
    Aug 7, 2019 at 20:33

3 Answers 3


John answered the question already very well but I want to draw your attention to this hidden documentation gem by the Packaging PM Dileep Burki. It helped to feel safe with Unlocked Packages.

enter image description here

In those sections, it really describes how and that unlocked packages were designed for such refactorings.

How can I refactor my package?

Let’s suppose you have installed ver 1 of your unlocked package pkg1. As part of refactoring your App, you decide to move some metadata from pkg1 to a new package pkg2.

You will refactor the package by following these steps:

  1. Identify the metadata that you want to move out of pkg1.
  2. Remove metadata identified in step 1 from pkg1 repo and create ver 2 of pkg1.
  3. Add the metadata identified in step 1 to a different DX folder / project / repo and create ver 1 of pkg2 using that metadata. You may add other metadata to complete pkg2.
  4. After proper testing and UAT, install ver 2 of pkg1 in the org where ver1 of pkg1 has been installed.
  5. Install ver1 of pkg2 in the same org.
  6. At the end of step 5, the metadata identified in step 1 would have migrated from pkg1 to pkg2.

Can I downgrade my package?

You should consider any downgrade of a package carefully. Package downgrades can fail due to dependency scenarios. For E.g.: if ver 3.0 has an apex class that is referenced by another apex class in a different package, downgrading to ver 2.0 would fail with a user-friendly error message if that apex class is not present in ver 2.0 of the package.

In the context of packaging, a downgrade is installing a lower version of a package on top of a higher version. For E.g.: this is when you try to install ver 2.0 of your package in an org where ver 3.0 has been installed.

When you downgrade a package, the following occurs:

  1. The metadata of the package version (ver 2.0 in this example) is deployed to the target org.
  2. Any metadata that is present as part of the package in the installed org (ver 3.0 metadata in this example) is modified, deleted or deprecated based on whether they are present in the version being installed. For E.g.: an apex class will be modified to the ver 2.0 copy of it as part of the downgrade. If a custom object foo__c is not present in ver 2.0 but present in ver 3.0, foo__c is marked deprecated (See here for more info about what deprecated means in this context). If a report object is not present in ver 2.0 but present in ver 3.0, the report is deleted from the org.
  • 3
    Yeah. What robert-sösemann said! :-D Aug 7, 2019 at 14:17
  • Is there a better procedure for fields attached to packages? I have to log on my sandbox/production and remove those fields from the unlocked package A before I can install package B which contains those field right?
    – Edmondo
    Sep 6, 2020 at 7:25

Is there a process that allows us to safely move a piece of metadata from a package to one of its dependent packages?

Yes. Once a piece of metadata is released via an unlocked package, you can remove it from the package down the road in a subsequent package version. So the metadata item is no longer in the latest package version. When you install that version to an org where a previous version was installed, the installation event will effectively "release the metadata component back to Happy Soup". Pay attention to the --upgradetype flag on the force:package:install command. See documentation about this flag. Don't worry about screw ups - I have "screwed up" several times myself. This will help you adjust things.

Also, can we move metadata from a dependent package to a base package as well?

Oh yes. Basically, it is the same approach as above. Identify the components you want to move. Release them from the original package. Include them in the new package. Once you install new package to the org, it "assumes ownership" of that "loose metadata."

Hope this helps.


Both answers are pretty good, just would like to add on based on the official document.

You can deprecate metadata in an unlocked package, move that metadata to a new package, and then install the new package in your production org. As you create more unlocked packages, you can refactor your package and move metadata from one unlocked package to another unlocked package if necessary.

To move production metadata from package A to package B, follow these steps.

  • Identify the metadata to be moved from package A to package B.
  • Remove the metadata from package A, create a version, and release the package.
  • Add the metadata to package B, create a version, and release the package.
  • In your production org, upgrade package A.
  • In your production org, install package B.
  • Your metadata is now a part of package B in your production org.

Reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_migrate_metadata.htm?search_text=Package%20A%20to%20package%20B

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .