From d8ca7dd34cf2ff4274bfe7537936a650973580d0 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 22 Oct 2024 11:52:39 +0200 Subject: [PATCH] docs/tooling/local-dev: update workspace linking docs Signed-off-by: Patrik Oldsberg --- .../local-dev/linking-local-packages.md | 86 +++---------------- 1 file changed, 13 insertions(+), 73 deletions(-) diff --git a/docs/tooling/local-dev/linking-local-packages.md b/docs/tooling/local-dev/linking-local-packages.md index eb2a2cba37..a7e967ac59 100644 --- a/docs/tooling/local-dev/linking-local-packages.md +++ b/docs/tooling/local-dev/linking-local-packages.md @@ -18,89 +18,29 @@ together: For example, you might want to make modifications to `@backstage/core-plugin-api` and try them out in your company's instance of Backstage. -## Linking in Backstage NPM Packages +## External workspace linking -To link in external packages, add them to your root `package.json` and `lerna.json` -`"workspace"` paths. These can be either relative or absolute paths with or without -globs. +:::info +Workspace linking is an experimental feature and may not work in all cases. +It currently only works for frontend packages. +::: -For example: +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. -```json title="/lerna.json" -... -"packages": [ - "packages/*", - "plugins/*", - "../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api -], -... -``` +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. -```json title="/package.json" -... -"workspaces": { - "packages": [ - "packages/*", - "plugins/*", - "../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api - ], -} -... -``` - -Now reinstall all packages from the root to make yarn set up symlinks from your application to the core Backstage clone: +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: ```bash -yarn install +yarn start --link ../../../backstage ``` -## Making Backstage Changes +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 this in place you can now modify the `@backstage/core-plugin-api` package -within the main repo, and have those changes be reflected and tested in your -app. Simply run your app using `yarn dev` (or `yarn start` for just frontend) as -normal. +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. ## Common Problems -### Backend Issues +### React errors -For backend packages you need to make sure that linked packages are -not dependencies of any non-linked package. If you for example want to work on -`@backstage/backend-common`, you need to also link in other backend plugins and -packages that depend on `@backstage/backend-common`, or temporarily disable -those plugins in your backend. This is because the transformation of backend -module tree stops whenever a non-local package is encountered, and from that -point node will `require` packages directly for that entire module subtree. - -### Typescript Issues - -Type checking can also have issues when linking in external packages, since the -linked in packages will use the types in the external project and dependency -version mismatches between the two projects may cause errors. To fix any of -those errors you need to sync versions of the dependencies in the two projects. -A simple way to do this can be to copy over `yarn.lock` from the external -project and run `yarn install`, although this is quite intrusive and can cause -other issues in existing projects, so use this method with care. It can often be -best to simply ignore the type errors, as app serving will work just fine -anyway. - -Another issue with type checking is that the incremental type cache doesn't -invalidate correctly for the linked in packages, causing type checking to not -reflect changes made to types. You can work around this by either setting -`compilerOptions.incremental = false` in `tsconfig.json`, or by deleting the -types cache folder `dist-types` before running `yarn tsc`. - -### Version Issues - -While `yarn install` might not error, it does not mean that the linking worked properly. -You will know that linking worked properly when: - -1. Your Backstage application root `/node_modules/@backstage/[some package]` is a symlink -2. Your Backstage application `/packages/app/node_modules` and `/packages/backend/node_modules` does - not contain the package you are attempting to link! - -If you see Yarn continuing to download the package you are trying to link from NPM, you might need to be -explicit in your `package.json` version so that it exactly matches what you have in the cloned Backstage -repository on your machine. For example, if you have cloned `/plugins/catalog` with version -`"version": "1.19.1-next.1"` you will need to be explicit in your application to point to `"1.19.1-next.1"`. +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.