Remove accidental import of semver
Signed-off-by: Marcus Crane <marcus.crane@lightspeedhq.com>
This commit is contained in:
Marcus Crane
@@ -212,7 +212,7 @@ future.
|
||||
common for companies to have their own npm registry, and this file makes sure
|
||||
that this folder always uses the public registry.
|
||||
|
||||
- [`.yarnrc`](https://github.com/backstage/backstage/tree/master/.yarnrc) -
|
||||
- [`.yarnrc.yml`](https://github.com/backstage/backstage/tree/master/.yarnrc.yml) -
|
||||
Enforces "our" version of Yarn.
|
||||
|
||||
- [`app-config.yaml`](https://github.com/backstage/backstage/tree/master/app-config.yaml) -
|
||||
|
||||
@@ -46,7 +46,7 @@ The source code is available here:
|
||||
Create a new `packages/backend/src/plugins/todolist.ts` with the following content:
|
||||
|
||||
```javascript
|
||||
import { IdentityClient } from '@backstage/plugin-auth-node';
|
||||
import { DefaultIdentityClient } from '@backstage/plugin-auth-node';
|
||||
import { createRouter } from '@internal/plugin-todo-list-backend';
|
||||
import { Router } from 'express';
|
||||
import { PluginEnvironment } from '../types';
|
||||
@@ -57,7 +57,7 @@ The source code is available here:
|
||||
}: PluginEnvironment): Promise<Router> {
|
||||
return await createRouter({
|
||||
logger,
|
||||
identity: IdentityClient.create({
|
||||
identity: DefaultIdentityClient.create({
|
||||
discovery,
|
||||
issuer: await discovery.getExternalBaseUrl('auth'),
|
||||
}),
|
||||
|
||||
@@ -154,3 +154,39 @@ schema migrations as well, but you can do so in any manner that you see fit.
|
||||
See the [Knex library documentation](http://knexjs.org/) for examples and
|
||||
details on how to write schema migrations and perform SQL queries against your
|
||||
database..
|
||||
|
||||
## Making Use of the User's Identity
|
||||
|
||||
The Backstage backend comes with a facility for retrieving the identity of the
|
||||
logged in user.
|
||||
|
||||
As part of the environment object that is passed to your `createPlugin`
|
||||
function, there is a `identity` field. You can use that to get an identity
|
||||
from the request.
|
||||
|
||||
```ts
|
||||
// in packages/backend/src/plugins/carmen.ts
|
||||
export default async function createPlugin(
|
||||
env: PluginEnvironment,
|
||||
): Promise<Router> {
|
||||
return await createRouter({
|
||||
model: model,
|
||||
logger: env.logger,
|
||||
identity: env.identity,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The plugin can then extract the identity from the request.
|
||||
|
||||
```ts
|
||||
export async function createRouter(
|
||||
options: RouterOptions,
|
||||
): Promise<express.Router> {
|
||||
const router = Router();
|
||||
|
||||
router.post('/example', async (req, res) => {
|
||||
const identity = await identity.getIdentity({ request: req });
|
||||
...
|
||||
});
|
||||
```
|
||||
|
||||
+2
-1
@@ -55,6 +55,7 @@ process is used to release an emergency fix as version `6.5.1` in the patch rele
|
||||
of the repo in order to convert your changeset into package version bumps and changelog entries.
|
||||
Commit these changes as a second `"Generated release"` commit.
|
||||
- [ ] Create PR towards the base branch (`patch/v1.18.0`) containing the two commits.
|
||||
- [ ] Add a PR body, it will be used as the release description. Typically something like "This release fixes ...".
|
||||
- [ ] Review/Merge the PR into `patch/v1.18.0`. This will automatically trigger a release.
|
||||
|
||||
- [ ] Look up the new version of our package in the patch PR as well as the new release
|
||||
@@ -65,5 +66,5 @@ process is used to release an emergency fix as version `6.5.1` in the patch rele
|
||||
master branch as well. Create a PR that contains the following:
|
||||
|
||||
- [ ] The fix, which you can likely cherry-pick from your patch branch: `git cherry-pick origin/patch/v1.18.0^`
|
||||
- [ ] An updated `CHANGELOG.md` of all patched packages from the tip of the patch branch, `git checkout origin/patch/v1.18.0 -- {packages,plugins}/*/CHANGELOG.md`.
|
||||
- [ ] An updated `CHANGELOG.md` of all patched packages from the tip of the patch branch, `git checkout origin/patch/v1.18.0 -- {packages,plugins}/*/CHANGELOG.md`. Note that if the patch happens after any next-line releases you'll need to restore those entries in the changelog, placing the patch release entry beneath any next-line release entries.
|
||||
- [ ] A changeset with the message "Applied the fix from version `6.5.1` of this package, which is part of the `v1.18.1` release of Backstage."
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,205 @@
|
||||
---
|
||||
id: react-router-stable-migration
|
||||
title: React Router 6.0 Migration
|
||||
description: Guide for how to migrate from React Router v6 beta to React Router v6 stable
|
||||
---
|
||||
|
||||
Backstage has for a long time been using `react-router` version `6.0.0-beta.0`.
|
||||
We adopted this unstable version because v6 had some new features that fit
|
||||
really well with Backstage, particularly relative routing. Because we jumped on
|
||||
this early and unstable version, we knew that we would at some point need a
|
||||
breaking migration to the stable version of `react-router` v6, which is the
|
||||
point we're at now!
|
||||
|
||||
This migration is required but controlled by each app, meaning that you choose
|
||||
when you want to migrate your app. There will however be some point in the
|
||||
future where we drop support for the beta version of `react-router`, at which
|
||||
time you would be forced to migrate.
|
||||
|
||||
The stable version of React Router v6 brings a number of improvements and bug
|
||||
fixes. Notably, the way that paths are resolved has been improved, which fixes a
|
||||
bug where paths like `/catalog` and `/catalog-import` could get confused.
|
||||
|
||||
## Migration
|
||||
|
||||
### Step 1 - Upgrade to Backstage 1.6
|
||||
|
||||
The first Backstage release to support `react-router` v6 is `1.6`. You should upgrade to this version first before you start migrating. If you are an early bird and want to try out migration before that release, it is also shipped in `1.6.0-next.1`.
|
||||
|
||||
### Step 2 - Move `react-router` to `peerDependencies`
|
||||
|
||||
It's important that only one version of `react-router` is installed in the
|
||||
project at a time. Similar to how the `react` version is handled, all plugins
|
||||
and packages now declare a peer dependency on the React Router dependencies,
|
||||
rather than a direct dependency. The only exception to this is the app package
|
||||
(in `packages/app/package.json`), which has the direct dependencies that end up
|
||||
deciding what version of React Router that you are using in your project.
|
||||
|
||||
Your internal packages might specify a dependency on `react-router` or `react-router-dom` in their `package.json`, and it's important that those are converted to `peerDependencies` so that we can control the version of `react-router` in the app `package.json`.
|
||||
|
||||
You can automate this step by running the following command:
|
||||
|
||||
```bash
|
||||
yarn backstage-cli migrate react-router-deps
|
||||
```
|
||||
|
||||
For those interested in doing this manually, apply the below change to all `package.json` files except the one at `packages/app/package.json` or any other app packages. Skip moving any dependencies that don't already exist, and move both `dependencies` and `devDependencies`.
|
||||
|
||||
```diff
|
||||
dependencies {
|
||||
...
|
||||
- "react-router-dom": "^6.0.0-beta.0",
|
||||
- "react-router": "^6.0.0-beta.0"
|
||||
},
|
||||
peerDependencies: {
|
||||
...
|
||||
+ "react-router-dom": "6.0.0-beta.0 || ^6.3.0",
|
||||
+ "react-router": "6.0.0-beta.0 || ^6.3.0"
|
||||
},
|
||||
```
|
||||
|
||||
### Step 3 - Ensure that your external plugins are updated
|
||||
|
||||
It's important that you also update your external plugins to their latest version as these will have to perform the same `peerDependencies` update.
|
||||
|
||||
During this migration there may be external plugins that need updating. If you encounter any plugins outside of the `@backstage` scope that are incompatible with your installation, make sure to check for an existing issue or raise a new one at the plugin's GitHub repository.
|
||||
|
||||
### Step 4 - Bump the React Router dependencies in your app.
|
||||
|
||||
Now it's time to do the actual migration to the latest version of React Router. At this time of writing that is `6.3.0`, but that is of course a moving target.
|
||||
|
||||
The first step is to modify `packages/app/package.json`:
|
||||
|
||||
```diff
|
||||
- "react-router": "6.0.0-beta.0",
|
||||
- "react-router-dom": "6.0.0-beta.0",
|
||||
+ "react-router": "^6.3.0",
|
||||
+ "react-router-dom": "^6.3.0",
|
||||
```
|
||||
|
||||
In case you happen to have multiple app packages in your project, apply the same change to all those packages.
|
||||
|
||||
Once the change has been made, run `yarn install`, and then `yarn why react-router` to validate the installation. You should see the following line in the log as the only resulting entry:
|
||||
|
||||
```
|
||||
=> Found "react-router@6.3.0"
|
||||
```
|
||||
|
||||
If you see multiple entries, and especially `=> Found "react-router@6.0.0-beta.0"`, then your dependencies have not yet been fully migrated to support React Router v6 stable. Double check the steps above, using the information that the Yarn `why` command logged. Repeat the same process for `yarn why react-router-dom`.
|
||||
|
||||
If you end up being stuck not being able to move your entire project to stable versions cleanly, then you can use Yarn `"resolutions"` overrides in your root `package.json`. Try to avoid this option as it may lead to hidden breakages at runtime, and verify any plugins that needed the override. A better option is likely to hold off migrating for a while until plugins have had time to be updated.
|
||||
|
||||
### Step 5 - Breaking Changes
|
||||
|
||||
For a new app created with `npx @backstage/create-app`, the above steps are all you need to do. If you have created internal plugins and customizations then be sure to review the breaking changes in the [React Router changelog](https://reactrouter.com/docs/en/v6/upgrading/reach#breaking-updates) and validate all parts of your app. We've summarized the most important breaking changes below.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
See [changelog](https://reactrouter.com/docs/en/v6/upgrading/reach#breaking-updates) for a full list of breaking changes. Below we highlight a couple of the most important ones.
|
||||
|
||||
### Route paths
|
||||
|
||||
`Route` components must always contain a `path` or `index` prop.
|
||||
|
||||
```tsx
|
||||
<Routes>
|
||||
{/* Invalid */}
|
||||
<Route element={<Example />} />
|
||||
|
||||
{/* Valid */}
|
||||
<Route path="/" element={<Example />} />
|
||||
|
||||
{/* Valid but discouraged due to incompatibility with react-router beta */}
|
||||
<Route index element={<Example />} />
|
||||
</Routes>
|
||||
```
|
||||
|
||||
Absolute route paths within each `Routes` element must now match their own location, meaning that the following is invalid:
|
||||
|
||||
```tsx
|
||||
<Routes>
|
||||
<Route path="/foo">
|
||||
<Route path="/bar" /> {/* INVALID, must be "/foo/bar" or "bar" */}
|
||||
</Route>
|
||||
</Routes>
|
||||
```
|
||||
|
||||
### Routes and Route components
|
||||
|
||||
The `Routes` and `Route` component both received a large related breaking changes. It is no longer possible
|
||||
to have anything but `Route` elements and React fragments be a child of a `Routes` element. This means that
|
||||
structures like these:
|
||||
|
||||
```tsx
|
||||
<Routes>
|
||||
<MyComponent path="/foo" />
|
||||
...
|
||||
</Routes>
|
||||
```
|
||||
|
||||
need to be migrated to this:
|
||||
|
||||
```tsx
|
||||
<Routes>
|
||||
<Route path="/foo" element={<MyComponent />} />
|
||||
...
|
||||
</Routes>
|
||||
```
|
||||
|
||||
Somewhat related to the `Routes` change, it is no longer possible to render a
|
||||
`Route` element by itself, outside of a `Routes` wrapper. Previously, rendering
|
||||
such a `Route` element would cause the contents of its `element` prop to be
|
||||
rendered instead, but it will now throw an error.
|
||||
|
||||
### `PermissionedRoute`
|
||||
|
||||
Because of the above change, the `PermissionedRoute` component no longer works in all situations with React Router v6 stable. It has been deprecated in favor of the new `RequirePermission` component, which can be placed anywhere in order to perform a permissions check.
|
||||
|
||||
It's crucial that you update to `RequirePermission` at the same time as you update to React Router v6 stable as the `PermissionedRoute` component will no longer function.
|
||||
|
||||
```diff
|
||||
- <PermissionedRoute
|
||||
- path="/catalog-import"
|
||||
- permission={catalogEntityCreatePermission}
|
||||
- element={<CatalogImportPage />}
|
||||
+ <Route
|
||||
+ path="/catalog-import"
|
||||
+ element={
|
||||
+ <RequirePermission permission={catalogEntityCreatePermission}>
|
||||
+ <CatalogImportPage />
|
||||
+ </RequirePermission>
|
||||
+ }
|
||||
/>
|
||||
```
|
||||
|
||||
### `<Navigate />` component
|
||||
|
||||
When migrating over to React Router v6 stable, you might also see browser console warnings for the `Navigate` component. This will need to be wrapped up in a `Route` component with the `Navigate` component in the `element` prop.
|
||||
|
||||
```diff
|
||||
- <Navigate key="/" to="catalog" />
|
||||
+ <Route path="/" element={<Navigate to="/catalog" />} />
|
||||
```
|
||||
|
||||
### `NavLink`
|
||||
|
||||
The `NavLink` component no longer has the `activeClassName` and `activeStyle` props. Instead, the `className` and `style` props accept a callback that receives a boolean indicating whether the link is active.
|
||||
|
||||
## For Plugin Authors
|
||||
|
||||
There are a few things to keep in mind when migrating a published plugin. You of course need to make sure that dependencies on React Router are moved to `peerDependencies` as described above.
|
||||
In addition, you need to make sure that your plugin truly is compatible with both versions of React Router at runtime. To help you achieve that, you can follow these additional guidelines:
|
||||
|
||||
- Bump the version of `react-router` and `react-router-dom` in your own project to use the stable version. Place them in `devDependencies` if your plugin is a single package project. The stable version is more strict, so this is the better baseline to work from.
|
||||
- Make sure all `Route` elements have a `path` prop. Do not use the new `index` props, as it is not supported by the beta version. Use `path="/"` for the index routes within a `Routes`.
|
||||
- If you are using `NavLink`, use both the new and old APIs simultaneously, and work around any TypeScript errors.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Check the browser console for React Router related error messages.
|
||||
|
||||
Check `yarn.lock` for packages depending on older versions of `react-router`:
|
||||
|
||||
```bash
|
||||
yarn why react-router
|
||||
```
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
id: yarn-migration
|
||||
title: Migration to Yarn 3
|
||||
description: Guide for how to migrate a Backstage project to use Yarn 3
|
||||
---
|
||||
|
||||
> NOTE: We do not yet recommend all projects to migrate to Yarn 3. Only do so if you have specific reasons for it.
|
||||
|
||||
While Backstage projects created with `@backstage/create-app` use [Yarn 1](https://classic.yarnpkg.com/) by default, it
|
||||
is possible to switch them to instead use [Yarn 3](https://yarnpkg.com/). Tools like `yarn backstage-cli versions:bump` will
|
||||
still work, as they recognize both lockfile formats.
|
||||
|
||||
## Migration
|
||||
|
||||
In addition to this guide, also be sure to check out the [Yarn migration guide](https://yarnpkg.com/getting-started/migration) as well.
|
||||
|
||||
### Ignore File Updates
|
||||
|
||||
First off, be sure to have the updated ignore entries in your app. These are included in all newly created projects, but might be missing in yours:
|
||||
|
||||
Add the following to `.gitignore`:
|
||||
|
||||
```gitignore
|
||||
# Yarn 3 files
|
||||
.pnp.*
|
||||
.yarn/*
|
||||
!.yarn/patches
|
||||
!.yarn/plugins
|
||||
!.yarn/releases
|
||||
!.yarn/sdks
|
||||
!.yarn/versions
|
||||
```
|
||||
|
||||
And this to `.dockerignore`:
|
||||
|
||||
```gitignore
|
||||
.yarn/cache
|
||||
.yarn/install-state.gz
|
||||
```
|
||||
|
||||
### Installation
|
||||
|
||||
Let's move on to the actual installation. We'd recommend making separate Git commits of most of these steps, in case you need to go back and debug anything. To install Yarn 3, run the following command in the project root:
|
||||
|
||||
```bash
|
||||
yarn set version stable
|
||||
```
|
||||
|
||||
We'll need the Yarn workspace tools plugin later on, so let's install that too:
|
||||
|
||||
```bash
|
||||
yarn plugin import @yarnpkg/plugin-workspace-tools
|
||||
```
|
||||
|
||||
Now we're ready to re-install all dependencies. This will update your `yarn.lock` and switch the project to use `node-modules` as the Yarn node linker.
|
||||
|
||||
In case you had a `.yarnrc` you can delete it now, but be sure to migrate over any options to `.yarnrc.yml`. See the [Yarn configuration docs](https://yarnpkg.com/configuration/manifest) for a full list of options. For example, `registry` is now `npmRegistryServer`, and `network-timeout` is `httpTimeout`.
|
||||
|
||||
### Migrate Usage
|
||||
|
||||
At this point you'll be all set up with Yarn 3! What remains is to migrate any usage of Yarn according to their [migration guide](https://yarnpkg.com/getting-started/migration). For example, any `yarn install --frozen-lockfile` commands should be replaced with `yarn install --immutable`.
|
||||
|
||||
You'll also need to update any `Dockerfile`s to add instructions to copy in your Yarn 3 installation into the image:
|
||||
|
||||
```Dockerfile
|
||||
COPY .yarn ./.yarn
|
||||
COPY .yarnrc.yml ./
|
||||
```
|
||||
|
||||
The `--production` flag to `yarn install` has been removed in Yarn 3, instead you need to use `yarn workspaces focus --all --production` to avoid installing development dependencies in your production deployment. A tradeoff of this is that `yarn workspaces focus` does not support the `--immutable` flag.
|
||||
|
||||
```Dockerfile
|
||||
RUN yarn workspaces focus --all --production && rm -rf "$(yarn cache clean)"
|
||||
```
|
||||
|
||||
If you have any internal CLI tools in your project that are exposed through `"bin"` entries in `package.json`, then you'll need to add these packages as dependencies in your project root `package.json`. This is to make sure Yarn picks up the executables and makes them available through `yarn <executable>`.
|
||||
Reference in New Issue
Block a user