Create a Salesforce DX Project from Existing Source

If you’re a Salesforce developer, partner, or ISV, you likely have existing source in a managed package in your packaging org or application source in your sandbox or production org. Before you begin using Salesforce DX, retrieve the existing source into a Salesforce DX project.

Create a Salesforce DX project.
Change to the project directory.

Retrieve your source by running the project retrieve start command. The location and format of your current source determine the command flags you must use.

Format and Location of Current Source Command To Retrieve Your Source

You’re a partner who has your source already defined as a managed package in your packaging org. sf project retrieve start --package-name <package-name> --target-org <sourceOrg-username-or-alias>. The --target-org flag specifies the username or alias for the source org (such as a packaging org) from which you’re retrieving the source. The --package-name flag specifies the package name; if the name contains a space, enclose it in double quotes. By default, the command creates a package directory, with the same name as your package, in the DX project directory. The command then retrieves the source from your package and organizes it in the new directory using the standard DX source format structure. Use the --output-dir to specify a different directory; the command creates the directory if it doesn’t exist.

You have a manifest file, typically called package.xml, that defines your unpackaged source in a sandbox or production org. sf project retrieve start --manifest <manifest-file> --target-org <sourceOrg-username-or-alias>. The --target-org flag specifies the username or alias for the org (such as a sandbox or production) from which you’re retrieving the source. The --manifest flag indicates the path to the manifest file, typically called package.xml. By default, the command retrieves the source into the existing force-app package directory of your DX project. Use the --output-dir to specify a different directory; the command creates the directory if it doesn’t exist.

Format and Location of Current Source	Command To Retrieve Your Source
You’re a partner who has your source already defined as a managed package in your packaging org.	`sf project retrieve start --package-name <package-name> --target-org <sourceOrg-username-or-alias>`. The `--target-org` flag specifies the username or alias for the source org (such as a packaging org) from which you’re retrieving the source. The `--package-name` flag specifies the package name; if the name contains a space, enclose it in double quotes. By default, the command creates a package directory, with the same name as your package, in the DX project directory. The command then retrieves the source from your package and organizes it in the new directory using the standard DX source format structure. Use the `--output-dir` to specify a different directory; the command creates the directory if it doesn’t exist.
You have a manifest file, typically called package.xml, that defines your unpackaged source in a sandbox or production org.	`sf project retrieve start --manifest <manifest-file> --target-org <sourceOrg-username-or-alias>`. The `--target-org` flag specifies the username or alias for the org (such as a sandbox or production) from which you’re retrieving the source. The `--manifest` flag indicates the path to the manifest file, typically called `package.xml`. By default, the command retrieves the source into the existing `force-app` package directory of your DX project. Use the `--output-dir` to specify a different directory; the command creates the directory if it doesn’t exist.

If you already have a repo that follows the directory structure created from a Metadata API retrieve, then your source files in the repo are in metadata format. You can convert these files into source format and include them in your Salesforce DX project. See Convert Files in Metadata Format to Source Format for details.

If the retrieve created a package directory in your project, add it to your sfdx-project.json file.

Do you have source in a sandbox or production org, but you don’t have a manifest file (package.xml) for retrieving it to your project? Use the project generate manifest CLI command to create one. For example, this command generates a manifest from the metadata components in the org with the alias prod-org.

See the command help for more examples and information.

You can also refer to Sample package.xml Manifest Files in the Metadata API Developer Guide.

See Also