Review instructions to link/unlink a module/package

[cmoulliard]

TODO

Review instructions to link/unlnk a module/package within the DEVELOPER.md file

Producer of package

TO LINK
 ~/code/openshift/backstage-quarkus-plugins/plugins/quarkus-console 
yarn link
success Registered "@qshift/plugin-quarkus-console".

VERIFY
ls -la ~/.config/yarn/link/@qshift                
total 0
drwxr-xr-x@ 3 cmoullia  staff  96 Feb  9 06:51 .
drwxr-xr-x@ 3 cmoullia  staff  96 Jan 15 21:39 ..
lrwxr-xr-x@ 1 cmoullia  staff  76 Feb  9 06:51 plugin-quarkus-console -> ../../../../code/openshift/backstage-quarkus-plugins/plugins/quarkus-console

TO UNLINK
yarn unlink
success Unregistered "@qshift/plugin-quarkus-console".
info You can now run `yarn unlink "@qshift/plugin-quarkus-console"` in the projects where you no longer want to use this package.
✨  Done in 0.02s.

Consumer of the package

TO LINK
~/code/openshift/fork-backstage-playground

yarn link "@qshift/plugin-quarkus-console"
success Using linked package for "@qshift/plugin-quarkus-console".
✨  Done in 0.04s.

ls -la node_modules/@qshift/plugin-quarkus-console 
lrwxr-xr-x@ 1 cmoullia  staff  63 Feb  8 21:47 node_modules/@qshift/plugin-quarkus-console -> ../../../../../.config/yarn/link/@qshift/plugin-quarkus-console

TO UNLINK
yarn unlink "@qshift/plugin-quarkus-console"      

success Removed linked package "@qshift/plugin-quarkus-console".

Notes:

• Links are stored here: ls -la ~/.config/yarn/link/@qshift
• Unlink the consumer before the producer and reinstall the package: yarn install

See: https://blog.alyssaholland.me/npm-yarn-link

[cmoulliard]

!! There is still a big big issue as we got this error when frontend is started yarn start

ERROR in ../../../backstage-quarkus-plugins/node_modules/@material-ui/core/esm/SwipeableDrawer/SwipeArea.js 4:0-31
Module not found: 
Error: Can't resolve 'react' in '/Users/cmoullia/code/openshift/backstage-quarkus-plugins/node_modules/@material-ui/core/esm/SwipeableDrawer'

The solution is maybe to perform a yarn install within the project where plugin has been linked - https://backstage.io/docs/local-dev/linking-local-packages/

[cmoulliard]

Temporary workaround is todo

From the github plugin project AND if we modify the module quarkus-console, execute the following commands to copy the file files generated to the backstage app project

PLUGIN_NAME=quarkus-console
BACKSTAGE_APP_PATH=$HOME/code/openshift/fork-backstage-playground

yarn tsc; yarn build

cp -rf plugins/$PLUGIN_NAME/dist/ $BACKSTAGE_APP_PATH/node_modules/@qshift/plugin-$PLUGIN_NAME/dist

[cmoulliard]

There is still an issue after we merged the PR #45 where react packages have been added as DevDependencies

[cmoulliard]

Since we updated the plugins to use React 18 and playground has been bumped to 1.23.4, we got another error when we link the plugin within the playground backstage app => Cannot read properties of null (reading 'useContext')

Call Stack
 useContext
  backstage-quarkus-plugins/node_modules/react/cjs/react.development.js:1619:21
 useVersionedContext
  backstage-quarkus-plugins/node_modules/@backstage/version-bridge/dist/index.esm.js:59:59
 useEntity
  backstage-quarkus-plugins/node_modules/@backstage/plugin-catalog-react/dist/esm/useEntity-de64059a.esm.js:57:105
 useK8sObjectsResponse
  backstage-quarkus-plugins/plugins/quarkus-console/src/services/useK8sObjectsResponse.ts:21:90
 QuarkusApplicationInfo
  backstage-quarkus-plugins/plugins/quarkus-console/src/components/QuarkusApplicationInfo.tsx:39:123
 renderWithHooks
  node_modules/react-dom/cjs/react-dom.development.js:16305:18
 mountIndeterminateComponent
  node_modules/react-dom/cjs/react-dom.development.js:20069:13
 beginWork
  node_modules/react-dom/cjs/react-dom.development.js:21582:16
 HTMLUnknownElement.callCallback
  node_modules/react-dom/cjs/react-dom.development.js:4164:14
 Object.invokeGuardedCallbackDev
  node_modules/react-dom/cjs/react-dom.development.js:4213:16

Idea ? @iocanel

[cmoulliard]

I did some researches and was able to find an approach which is working:

• Plugins "that you currently develop" can be used part of a backstage project (aka backstage-playground)
• Plugins are linked to their parent project
• Only one node_modules repo is used/needed
• Frontend changes are detected when yarn dev runs and can be visualized
• Errors reported part of this ticket are gone including aldso the new one reported by react Dipatcher is null due to react versions conflict

Instructions

// From plugins project
rm -rf node_modules
ln -s $HOME/PATH_TO_BACKSTAGE_PLAYGROUND/node_modules ./node_modules

// From $HOME/PATH_TO_BACKSTAGE_PLAYGROUND
rm -rf node_modules

# Edit the packages/app/package.json to add/replace the following dependencies
"@qshift/plugin-quarkus": "link:../../../BACKSTAGE_QUARKUS_PLUGINS/plugins/quarkus",
 "@qshift/plugin-quarkus-console": "link:../../../BACKSTAGE_QUARKUS_PLUGINS/plugins/quarkus-console",
"styled-components": "^6.1.8",

# Edit the packages/app/package.json to add/replace the following dependencies
"@qshift/plugin-quarkus-backend": "link:../../../fork-backstage-quarkus-plugins/plugins/quarkus-backend",

// Yarn install and launch
yarn install
yarn dev

Remark: A side affect of the approach followed here is that some plugin's dependencies should be declared part of the backstage project. Is there an alternative ?

WDYT ? @iocanel

[cmoulliard]

I tested another approach using the workspace option as documented here: https://dev.to/limal/simplify-your-monorepo-with-npm-7-workspaces-5gmj

I then created symbolic links to point to our plugins like this

ln -s /Users/cmoullia/code/openshift/fork-backstage-quarkus-plugins/plugins/quarkus ./plugins/quarkus
ln -s /Users/cmoullia/code/openshift/fork-backstage-quarkus-plugins/plugins/quarkus-console ./plugins/quarkus-console
ln -s /Users/cmoullia/code/openshift/fork-backstage-quarkus-plugins/plugins/quarkus-backend ./plugins/quarkus-backend

and changed too the links of the app and backend

# Edit the packages/app/package.json to add/replace the following dependencies
"@qshift/plugin-quarkus": "link:../../plugins/quarkus",
"@qshift/plugin-quarkus-console": "link:../../plugins/quarkus-console",

# Edit the packages/app/package.json to add/replace the following dependencies
"@qshift/plugin-quarkus-backend": "link:../../plugins//plugins/quarkus-backend",

Unfortunately, we get again the error Dispatcher is not null as the plugin quarkus (= > QuarkusVersionList) uses a Hook which is loaded using the lib packaged under the plugin node_modules folder

@iocanel

[cmoulliard]

I experimented the approach documented here : https://github.com/backstage/backstage/blob/master/docs/local-dev/linking-local-packages.md without success

I changed within the root package.json file and lerna.json file the workspaces to be used

  },
  "workspaces": {
    "packages": [
      "packages/*",
      "plugins/*",
      "../fork-backstage-quarkus-plugins/plugins/*"
    ]
  },

and

{
  "packages": [
    "packages/*",
    "plugins/*",
    "../fork-backstage-quarkus-plugins/plugins/*"
  ],
...

Executed again yarn install and yarn dev

We got when we click on http://localhost:3000/create the dispatch error BUT this time reported by the plugin-scaffolder-react/ and component: <ScaffolderPageContextMenu>

dispatcher is null
Call Stack
 useState
  node_modules/@backstage/plugin-scaffolder-react/node_modules/react/cjs/react.development.js:1623:3
 ScaffolderPageContextMenu
  node_modules/@backstage/plugin-scaffolder-react/dist/alpha.esm.js:1463:82
 renderWithHooks
  node_modules/react-dom/cjs/react-dom.development.js:16305:27
 mountIndeterminateComponent
  node_modules/react-dom/cjs/react-dom.development.js:20069:13
 beginWork
  node_modules/react-dom/cjs/react-dom.development.js:21582:16
 callCallback
  node_modules/react-dom/cjs/react-dom.development.js:4164:14
 invokeGuardedCallbackDev
  node_modules/react-dom/cjs/react-dom.development.js:4213:16
 invokeGuardedCallback
  node_modules/react-dom/cjs/react-dom.development.js:4277:31
 beginWork$1
  node_modules/react-dom/cjs/react-dom.development.js:27446:28
 performUnitOfWork
  node_modules/react-dom/cjs/react-dom.development.js:26552:12

[cmoulliard]

Forget my last remark. @iocanel

I created a new backstage app 1.27, set the workspaces as I commented before, declared our plugins to play with QuarkusVersionList - see screenshot and that works without having to create ln -s :-)

Note: We will have to bump our backstage-playground to see if the react errors are gone !

[cmoulliard]

The approach works too on our backstage-playground project and react error are gone at the condition that we also first remove the yarn.lock file

// bastage-playground/package.json
  "workspaces": {
    "packages": [
      "../fork-backstage-quarkus-plugins/plugins/*",
      "packages/*",
      "plugins/*"
    ]
  },
  ...
rm -rf node_modules
rm yarn.lock
yarn install; yarn dev

[iocanel]

I think that I prefer the simplicity of the mono repo, as it allows faster development.

If we continue with the split repo, even if we solve the problem of linking project, we still have drawbacks like:

• Requires that we all devs the same directory structure and folder naming.
• Allow for things to get out of sync
  • When bumping a dependency in one project, things will be out of sync till the other project aligns.
  • When performing an incompatible change in one plugins (e.g. a refactoring).
• Overhead of monitoring multiple repos etc.

[cmoulliard]

Conclusion about this ticket:

• Don't use yarn link/unlink as it don't at all allow to handle one repository of node modules and will generate React errors as multiple copy of the libs exist
• Creating a link between the plugins node_modules folder and the target node_modules folder backstage app is an option as finally only one node_modules folder exists BUT a side affect of this approach is that some plugin's dependencies should be declared part of the parent project

The only viable approach to have one node_modules folder is to declare part of the root/parent project the list of the workspaces to be handled by yarn and to define there the path to the plugins project.