From 1b1aa9081910602ef597cac779911b120c490064 Mon Sep 17 00:00:00 2001
From: Joshua Jung <joshua.p.jung@gmail.com>
Date: Mon, 3 Jun 2024 14:10:10 -0500
Subject: [PATCH] Update linking packages documentation

Signed-off-by: Joshua Jung <joshua.p.jung@gmail.com>
---
 .../local-dev/linking-local-packages.md       | 68 ++++++++++++++++---
 1 file changed, 59 insertions(+), 9 deletions(-)

diff --git a/docs/tooling/local-dev/linking-local-packages.md b/docs/tooling/local-dev/linking-local-packages.md
index 40b722e302..eb2a2cba37 100644
--- a/docs/tooling/local-dev/linking-local-packages.md
+++ b/docs/tooling/local-dev/linking-local-packages.md
@@ -4,34 +4,68 @@ title: Linking in Local Packages
 description: How to link in other local packages into your Backstage monorepo
 ---
 
-It can often be useful to try out changes to the packages in the main Backstage
-repo within your own app. For example if you want to make modifications to
-`@backstage/core-plugin-api` and try them out in your app.
+## Why?
 
-To link in external packages, add them to your `package.json` and `lerna.json`
-workspace paths. These can be either relative or absolute paths with or without
-globs. For example:
+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:
 
-```json
+```text
+~/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.
+
+## Linking in Backstage NPM Packages
+
+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.
+
+For example:
+
+```json title="/lerna.json"
+...
 "packages": [
   "packages/*",
   "plugins/*",
   "../backstage/packages/core-plugin-api", // New path added to work on @backstage/core-plugin-api
 ],
+...
 ```
 
-Then reinstall packages to make yarn set up symlinks:
+```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:
 
 ```bash
 yarn install
 ```
 
+## Making Backstage Changes
+
 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.
 
-Note that for backend packages you need to make sure that linked packages are
+## Common Problems
+
+### Backend Issues
+
+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
@@ -39,6 +73,8 @@ 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
@@ -54,3 +90,17 @@ 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"`.