Ever since Winter '19, the project-scratch-def.json file has supported a settings section which, per the documentation, supports all of the Settings from the Metadata API. So if both are specified, which wins? Do we need to use project-def settings if we have a full set of -meta.xml files under force-app/main/default/settings? I've been trying to figure this out empirically with a project I've converted from MDAPI sources (from an existing org), but the DX push errors are often cryptic and I'm not sure what to change.

If there is a reason to use project-def settings over settings files (or cases where project-def settings are required), is there a tool to generate the project-def settings from the files? I don't want to transcribe these all by hand, and I don't want to reinvent any wheels if someone has already done this work. Looks like a conversion from xml to json with a little case adjustment thrown in.

1 Answer 1


The two types of settings are, as far as I can tell, used in tandem. Settings that are available in the Scratch Org Definition Configuration should be specified in the JSON. While it does require some upfront work, you will eventually want to do this if you ever plan on using Unlocked Packages. Also, some settings cannot be specified after org creation, as they literally require a Support ticket to set normally in production orgs; those should definitely be moved to the JSON file... and since you're moving some of them, you may as well take the time to do them all.

In regards to unlocked packages, using the JSON settings is important because most of the Settings objects can't be packaged at all, so if you don't specify them in the JSON file, your dependencies may not be satisfied and your unlocked package versions will fail to upload. For the remainder of the settings, they would be uploaded post-org-creation via force:source:deploy.

You must log in to answer this question.

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