Linking in Local Packages
Why?
If you are looking to make changes within the core Backstage repository and test those changes within your Backstage application, you will need to link the two together:
~/backstage // cloned from Github
~/my-backstage-application // generated using npx
For example, you might want to make modifications to @backstage/core-plugin-api and try them out in your company's
instance of Backstage.
External workspace linking
Workspace linking is an experimental feature and may not work in all cases.
The backstage-cli package start command that is used for local development of all packages supports a --link flag that can be used to link a single external workspace to the current workspace. It hooks into the module resolution and will override all imports of packages in the linked workspace to be imported from there instead. The only exception are the react and react-dom packages, which will always be resolved from the target package.
When linking an external workspace, make sure that dependencies are installed and up to date in both workspaces, and that the versions of react and react-dom are the same in both workspaces.
If you're within the packages/app folder inside your my-backstage-application workspace in the above example, you can link the backstage workspace using the following command:
yarn start --link ../../../backstage
The path provided to the --link option can be a relative or absolute path, and should point to the root of the external workspace.
With the start command up and running and serving the development version of your frontend app in the browser, you can now make changes to both workspaces and see the changes reflected in the browser.
You can also link backend packages using the exact same process, simply start your backend package with the same --link <workspace-path> option.
Common Problems
React errors
If you are encountering errors related to React, it is likely that the versions of React in the two workspaces are different. Make sure that the versions of react and react-dom are the same in both workspaces, or at least that they are in sync between the package that you're serving the app from and the external workspace.
Generating temporary patches
!!!info This feature is experimental and currently only supports Yarn workspaces. !!!
After making local changes to a package in an external workspace you might often want to merge and deploy these changes in your own project. You can use Yarn patches for this purpose, but it can be quite cumbersome to create these patches manually. To make this process easier, you can use yarn backstage-repo-tools generate-patch command from the @backstage/repo-tools package to generate a patch and resolution entries in the external workspace.
For example, if you've made changes to the @backstage/backend-app-api package in a local clone of the main backstage repository, you can generate a patch for your internal project as follows:
yarn backstage-repo-tools generate-patch @backstage/backend-app-api --target ../our-developer-portal
This will generate a patch file in your our-developer-portal workspace. The patch will be based on the most recently released version of the source package, with the additional changes on top.
If you want to base the patch on a different version of the source package, you can specify the version using the --base-version <version> option, and if you want to only use the patch for a specific version query, you can specify that using the --query <query> option.