paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 42 Packages Projects Releases Wiki Activity

yarn-plugin: add architecture overview to readme

Browse Source 
Signed-off-by: MT Lewis <mtlewis@users.noreply.github.com>
This commit is contained in:
MT Lewis
2025-01-07 20:15:02 +00:00
committed by Vincenzo Scamporlino
parent fd70d8661e
commit e400827873
1 changed files with 44 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/yarn-plugin/README.md
+44
View File
@@ -38,3 +38,47 @@ The plugin can be manually tested in any repository running at least yarn 4.1.1.
Sadly it can't be manually tested directly in the Backstage monorepo - since
packages in this repository use `workspace:^` dependencies, there's no use case
for the yarn plugin.
## Architecture
This section is intended for people working directly on this package. It
describes the architecture of the plugin, and the means by which it manages npm
package versions.
The Backstage yarn plugin operates on `backstage:^` version ranges in
package.json files using the following three components:
### `reduceDependency` hook
_Converts `backstage:^` to `backstage:^::backstage=1.34.0&npm=1.2.3`_
This hook is called by yarn when resolving direct and indirect dependencies in
the workspace, and allows modifying the version range. The yarn plugin uses this
hook to parameterize `backstage:^` ranges with the current Backstage version and
the corresponding npm package version from the manifest. This uses the system
built into yarn for adding parameters to version ranges. An
### `BackstageNpmResolver`
_Resolves the appropriate npm package for `backstage:^` ranges and adds the
`npm` range as a dependency_
The `BackstageNpmResolver` ensures that the lockfile contains entries for _both_
the `backstage:^` range, and the corresponding `npm:^<version>` range. Including
an entry for the `backstage:^` range means that tools that reconcile the
lockfile and package.json can match entries for Backstage packages together.
Including an entry for the corresponding `npm:` range ensures that dependencies
are not unlocked when switching between `backstage:^` and `npm:` ranges in the
lockfile, as happens when publishing the package or building a dist workspace
using `backstage-cli build-workspace`.
### `beforeWorkspacePacking` hook
_Replaces `backstage:^` ranges with the corresponding npm version ranges when
packing packages for publishing_
The yarn plugin is strictly optional, and intended to be opted-into in a
specific Backstage repository. As such, when publishing packages, all
`backstage:^` versions should be removed from the package.json and replaced with
the appropriate npm version ranges. This is handled by the
`beforeWorkspacePacking` hook.