Merge branch 'master' into add-topics-to-notification-settings
Signed-off-by: billyatroadie <bstalnaker@roadie.com>
This commit is contained in:
billyatroadie
@@ -37,7 +37,6 @@ components. For example, the
|
||||
[`ErrorApi`](../reference/core-plugin-api.errorapi.md) can be accessed like this:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { useApi, errorApiRef } from '@backstage/core-plugin-api';
|
||||
|
||||
export const MyComponent = () => {
|
||||
|
||||
@@ -151,3 +151,41 @@ To clarify how to utilize the Auditor feature effectively, we recommend explorin
|
||||
- It illustrates how to detail various `eventId` values and their corresponding `meta` fields (e.g., `queryType`, `actionType`) for different plugin operations.
|
||||
|
||||
These examples provide both a code-level demonstration and a documentation guideline for effectively utilizing the `AuditorService` to manage audit events within your Backstage plugins.
|
||||
|
||||
## Severity Log Level Mappings
|
||||
|
||||
The Auditor Service provides a way for plugins to log significant events, categorized by their severity. The `severityLogLevelMappings` configuration option enables you to customize how these severity levels are mapped to actual log levels within your Backstage backend, giving you precise control over the verbosity of your audit logs.
|
||||
|
||||
### Configuration
|
||||
|
||||
The `severityLogLevelMappings` are configured under the `backend.auditor` section of your `app-config.yaml` file. This structure allows you to specify the log level for each severity level supported by the Auditor Service. You can override individual severity levels without changing the entire mapping.
|
||||
|
||||
Example configuration:
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
auditor:
|
||||
severityLogLevelMappings:
|
||||
low: debug
|
||||
medium: info
|
||||
high: warn
|
||||
critical: error
|
||||
```
|
||||
|
||||
### Severity Levels and Default Mappings
|
||||
|
||||
The Auditor Service supports the following severity levels:
|
||||
|
||||
- `low`: Represents low-importance events, typically informational or debug-level.
|
||||
- `medium`: Represents events of moderate importance, requiring some attention.
|
||||
- `high`: Represents high-importance events, potentially indicating a problem or security issue.
|
||||
- `critical`: Represents critical events, requiring immediate attention.
|
||||
|
||||
By default, these severity levels are mapped to the following log levels:
|
||||
|
||||
- `low`: `debug`
|
||||
- `medium`: `info`
|
||||
- `high`: `info`
|
||||
- `critical`: `info`
|
||||
|
||||
As a result, medium, high, and critical events are logged as info-level events by default, while low-level events are treated as debug.
|
||||
|
||||
@@ -24,7 +24,6 @@ Create a new `packages/app/src/components/search/SearchPage.tsx` file in your
|
||||
Backstage app with the following contents:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { Content, Header, Page } from '@backstage/core-components';
|
||||
import { Grid, List, Card, CardContent } from '@material-ui/core';
|
||||
import {
|
||||
|
||||
@@ -242,8 +242,6 @@ which renderers to use. Note that the order of the renderers matters! The first
|
||||
Here is an example of customizing your `SearchPage`:
|
||||
|
||||
```tsx title="packages/app/src/components/searchPage.tsx"
|
||||
import React from 'react';
|
||||
|
||||
import { Grid, Paper } from '@material-ui/core';
|
||||
import BuildIcon from '@material-ui/icons/Build';
|
||||
|
||||
@@ -325,8 +323,6 @@ export const Root = ({ children }: PropsWithChildren<{}>) => {
|
||||
Assuming you have completely customized your SearchModal, here's an example that renders results with extensions:
|
||||
|
||||
```tsx title="packages/app/src/components/searchModal.tsx"
|
||||
import React from 'react';
|
||||
|
||||
import { DialogContent, DialogTitle, Paper } from '@material-ui/core';
|
||||
import BuildIcon from '@material-ui/icons/Build';
|
||||
|
||||
|
||||
@@ -442,7 +442,6 @@ import {
|
||||
EntityTypePicker,
|
||||
UserListPicker,
|
||||
} from '@backstage/plugin-catalog-react';
|
||||
import React from 'react';
|
||||
|
||||
export const CustomCatalogPage = () => {
|
||||
const orgName =
|
||||
|
||||
@@ -29,7 +29,6 @@ As an example, we will create a component that validates whether a string is in
|
||||
|
||||
```tsx
|
||||
//packages/app/src/scaffolder/ValidateKebabCase/ValidateKebabCaseExtension.tsx
|
||||
import React from 'react';
|
||||
import { FieldExtensionComponentProps } from '@backstage/plugin-scaffolder-react';
|
||||
import type { FieldValidation } from '@rjsf/utils';
|
||||
import FormControl from '@material-ui/core/FormControl';
|
||||
|
||||
@@ -18,8 +18,7 @@ This is the same [field](https://rjsf-team.github.io/react-jsonschema-form/docs/
|
||||
|
||||
The [createScaffolderLayout](https://backstage.io/docs/reference/plugin-scaffolder-react.createscaffolderlayout) function is used to mark a component as a custom step layout:
|
||||
|
||||
```ts
|
||||
import React from 'react';
|
||||
```tsx
|
||||
import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
|
||||
import {
|
||||
createScaffolderLayout,
|
||||
|
||||
@@ -181,8 +181,7 @@ provided by the Addon framework.
|
||||
|
||||
```tsx
|
||||
// plugins/your-plugin/src/addons/MakeAllImagesCatGifs.tsx
|
||||
|
||||
import React, { useEffect } from 'react';
|
||||
import { useEffect } from 'react';
|
||||
import { useShadowRootElements } from '@backstage/plugin-techdocs-react';
|
||||
|
||||
// This is a normal react component; in order to make it an Addon, you would
|
||||
|
||||
@@ -135,6 +135,7 @@ You can easily customize the TechDocs home page using TechDocs panel layout
|
||||
Modify your `App.tsx` as follows:
|
||||
|
||||
```tsx
|
||||
import { Fragment, PropsWithChildren } from 'react';
|
||||
import { TechDocsCustomHome } from '@backstage/plugin-techdocs';
|
||||
//...
|
||||
|
||||
@@ -175,7 +176,7 @@ const techDocsTabsConfig = [
|
||||
filterPredicate: filterEntity,
|
||||
panelType: 'TechDocsIndexPage',
|
||||
title: 'All',
|
||||
panelProps: { PageWrapper: React.Fragment, CustomHeader: React.Fragment, options: options },
|
||||
panelProps: { PageWrapper: Fragment, CustomHeader: Fragment, options: options },
|
||||
},
|
||||
],
|
||||
},
|
||||
@@ -184,7 +185,7 @@ const docsFilter = {
|
||||
kind: ['Location', 'Resource', 'Component'],
|
||||
'metadata.annotations.featured-docs': CATALOG_FILTER_EXISTS,
|
||||
}
|
||||
const customPageWrapper = ({ children }: React.PropsWithChildren<{}>) =>
|
||||
const customPageWrapper = ({ children }: PropsWithChildren<{}>) =>
|
||||
(<PageWithHeader title="Docs" themeId="documentation">{children}</PageWithHeader>)
|
||||
const AppRoutes = () => {
|
||||
<FlatRoutes>
|
||||
@@ -212,7 +213,7 @@ maintain such a component in a new directory at
|
||||
For example, you can define the following Custom home page component:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { ReactNode } from 'react';
|
||||
|
||||
import { Content } from '@backstage/core-components';
|
||||
import {
|
||||
@@ -232,7 +233,7 @@ import { EntityListDocsGrid } from '@backstage/plugin-techdocs';
|
||||
|
||||
export type CustomTechDocsHomeProps = {
|
||||
groups?: Array<{
|
||||
title: React.ReactNode;
|
||||
title: ReactNode;
|
||||
filterPredicate: ((entity: Entity) => boolean) | string;
|
||||
}>;
|
||||
};
|
||||
|
||||
@@ -40,7 +40,6 @@ Route refs do not have any behavior themselves. They are an opaque value that re
|
||||
The code snippet in the previous section does not indicate which plugin the route belongs to. To do so, you have to use it in the creation of any kind of routable extension, such as a page extension:
|
||||
|
||||
```tsx title="plugins/catalog/src/plugin.tsx"
|
||||
import React from 'react';
|
||||
import {
|
||||
createFrontendPlugin,
|
||||
createPageExtension,
|
||||
@@ -91,7 +90,6 @@ Route references can be used to link to page in the same plugin, or to pages in
|
||||
Suppose we are creating a plugin that renders a Catalog index page with a link to a "Foo" component details page. Here is the code for the index page:
|
||||
|
||||
```tsx title="plugins/catalog/src/components/IndexPage.tsx"
|
||||
import React from 'react';
|
||||
import { useRouteRef } from '@backstage/frontend-plugin-api';
|
||||
import { detailsRouteRef } from '../routes';
|
||||
|
||||
@@ -125,7 +123,6 @@ We use the `useRouteRef` hook to create a link generator function that returns t
|
||||
Let's see how the details page can get the parameters from the URL:
|
||||
|
||||
```tsx title="plugins/catalog/src/components/DetailsPage.tsx"
|
||||
import React from 'react';
|
||||
import { useRouteRefParams } from '@backstage/frontend-plugin-api';
|
||||
import { detailsRouteRef } from '../routes';
|
||||
|
||||
@@ -169,7 +166,6 @@ export const createComponentExternalRouteRef = createExternalRouteRef();
|
||||
External routes are also used in a similar way as regular routes:
|
||||
|
||||
```tsx title="plugins/catalog/src/components/IndexPage.tsx"
|
||||
import React from 'react';
|
||||
import { useRouteRef } from '@backstage/frontend-plugin-api';
|
||||
import { createComponentExternalRouteRef } from '../routes';
|
||||
|
||||
@@ -194,7 +190,6 @@ Given the above binding, using `useRouteRef(createComponentExternalRouteRef)` wi
|
||||
Now the only thing left is to provide the page and external route via a plugin:
|
||||
|
||||
```tsx title="plugins/catalog/src/plugin.tsx"
|
||||
import React from 'react';
|
||||
import {
|
||||
createFrontendPlugin,
|
||||
createPageExtension,
|
||||
@@ -333,7 +328,6 @@ export const detailsSubRouteRef = createSubRouteRef({
|
||||
Using subroutes in a page extension is as simple as this:
|
||||
|
||||
```tsx title="plugins/catalog/src/components/IndexPage.tsx"
|
||||
import React from 'react';
|
||||
import { Routes, Route, useLocation } from 'react-router-dom';
|
||||
import { useRouteRef } from '@backstage/frontend-plugin-api';
|
||||
import { indexRouteRef, detailsSubRouteRef } from '../routes';
|
||||
@@ -381,7 +375,6 @@ export const IndexPage = () => {
|
||||
This is how you can get the parameters of a sub route URL:
|
||||
|
||||
```tsx title="plugins/catalog/src/components/DetailsPage.tsx"
|
||||
import React from 'react';
|
||||
import { useParams } from 'react-router-dom';
|
||||
|
||||
export const DetailsPage = () => {
|
||||
@@ -405,7 +398,6 @@ export const DetailsPage = () => {
|
||||
Finally, see how a plugin can provide subroutes:
|
||||
|
||||
```tsx title="plugins/catalog/src/plugin.tsx"
|
||||
import React from 'react';
|
||||
import {
|
||||
createFrontendPlugin,
|
||||
createPageExtension,
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
id: migrations
|
||||
title: Frontend System Migrations
|
||||
sidebar_label: Migrations
|
||||
title: Frontend System Changelog
|
||||
sidebar_label: Changelog
|
||||
# prettier-ignore
|
||||
description: Migration documentation for different versions of the frontend system core APIs.
|
||||
description: Changelog documentation for different versions of the frontend system core APIs.
|
||||
---
|
||||
|
||||
> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.**
|
||||
|
||||
@@ -86,7 +86,6 @@ There is one more detail that we need to deal with before moving on. The `app.cr
|
||||
|
||||
```tsx title="in packages/app/src/index.tsx"
|
||||
import '@backstage/cli/asset-types';
|
||||
import React from 'react';
|
||||
import ReactDOM from 'react-dom/client';
|
||||
// highlight-remove-next-line
|
||||
import App from './App';
|
||||
|
||||
@@ -25,7 +25,6 @@ A component can be used for more than one extension, and it should be tested ind
|
||||
Use the `renderInTestApp` helper to render a given component inside a Backstage test app:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { screen } from '@testing-library/react';
|
||||
import { renderInTestApp } from '@backstage/frontend-test-utils';
|
||||
import { EntityDetails } from './plugin';
|
||||
@@ -44,7 +43,6 @@ describe('Entity details component', () => {
|
||||
To mock [Utility APIs](../architecture/33-utility-apis.md) that are used by your component you can use the `TestApiProvider` to override individual API implementations. In the snippet below, we wrap the component within a `TestApiProvider` in order to mock the catalog client API:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import { screen } from '@testing-library/react';
|
||||
import {
|
||||
renderInTestApp,
|
||||
|
||||
@@ -10,7 +10,7 @@ description: Extension blueprints provided by the frontend system and core featu
|
||||
|
||||
This section covers many of the [extension blueprints](../architecture/23-extension-blueprints.md) available at your disposal when building Backstage frontend plugins.
|
||||
|
||||
## Built-in extension blueprints
|
||||
## Extension blueprints in `@backstage/frontend-plugin-api`
|
||||
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Backstage frontend framework itself.
|
||||
|
||||
@@ -46,18 +46,26 @@ Icon bundle extensions provide the ability to replace or provide new icons to th
|
||||
|
||||
Translation extension provide custom translation messages for the app. They can be used both to override the default english messages to custom ones, as well as provide translations for additional languages.
|
||||
|
||||
## Core feature extension blueprints
|
||||
## Extension blueprints in `@backstage/plugin-catalog-react/alpha`
|
||||
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Backstage core feature plugins.
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Catalog plugin.
|
||||
|
||||
### EntityCard - [Reference](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/report-alpha.api.md)
|
||||
### EntityCard - [Example](https://github.com/backstage/backstage/blob/75e79518eafc6e6eb55585f166667418419662de/plugins/org/src/alpha.tsx#L27-L36)
|
||||
|
||||
Creates entity cards to be displayed on the entity pages of the catalog plugin. Exported as `EntityCardBlueprint`.
|
||||
|
||||
### EntityContent - [Reference](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/report-alpha.api.md)
|
||||
Avoid using `convertLegacyEntityCardExtension` from `@backstage/core-compat-api` to convert legacy entity card extensions to the new system. Instead, use the `EntityCardBlueprint` directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.
|
||||
|
||||
### EntityContent - [Example](https://github.com/backstage/backstage/blob/cd71065a02bed740011daee96a865108a785dff6/plugins/kubernetes/src/alpha/entityContents.tsx#L22-L34)
|
||||
|
||||
Creates entity content to be displayed on the entity pages of the catalog plugin. Exported as `EntityContentBlueprint`.
|
||||
|
||||
### SearchResultListItem - [Reference](https://github.com/backstage/backstage/blob/master/plugins/search-react/report-alpha.api.md)
|
||||
Avoid using `convertLegacyEntityContentExtension` from `@backstage/core-compat-api` to convert legacy entity content extensions to the new system. Instead, use the `EntityContentBlueprint` directly. The legacy converter is only intended to help adapt 3rd party plugins that you don't control, and doesn't produce as good results as using the blueprint directly.
|
||||
|
||||
## Extension blueprints in `@backstage/plugin-search-react/alpha`
|
||||
|
||||
These are the [extension blueprints](../architecture/23-extension-blueprints.md) provided by the Search plugin.
|
||||
|
||||
### SearchResultListItem - [Example](https://github.com/backstage/backstage/blob/8cb9a85596a5417a004811ffa429527b17ce9b72/plugins/catalog/src/alpha/searchResultItems.tsx#L19-L27)
|
||||
|
||||
Creates search result list items for different types of search results, to be displayed in search result lists. Exported as `SearchResultListItemBlueprint`.
|
||||
|
||||
@@ -12,6 +12,12 @@ The main concept is that routes, components, apis are now extensions. You can us
|
||||
|
||||
## Migrating the plugin
|
||||
|
||||
:::note Note
|
||||
|
||||
Unless you are migrating a plugin that is only used within your own project, we recommend all plugins to keep support for the old system intact. The code added in these examples should be added to a new `src/alpha.tsx` entry point of your plugin.
|
||||
|
||||
:::
|
||||
|
||||
In the legacy frontend system a plugin was defined in its own `plugin.ts` file as following:
|
||||
|
||||
```ts title="my-plugin/src/plugin.ts"
|
||||
@@ -19,7 +25,7 @@ In the legacy frontend system a plugin was defined in its own `plugin.ts` file a
|
||||
|
||||
export const myPlugin = createPlugin({
|
||||
id: 'my-plugin',
|
||||
apis: [],
|
||||
apis: [ ... ],
|
||||
routes: {
|
||||
...
|
||||
},
|
||||
@@ -29,17 +35,17 @@ In the legacy frontend system a plugin was defined in its own `plugin.ts` file a
|
||||
});
|
||||
```
|
||||
|
||||
In order to migrate the actual definition of the plugin you need to recreate the plugin using the new `createFrontendPlugin` utility exported by `@backstage/frontend-plugin-api`.
|
||||
The new `createFrontendPlugin` function doesn't accept apis anymore as apis are now extensions.
|
||||
In order to migrate the actual definition of the plugin you need to recreate the plugin using the new `createFrontendPlugin` utility exported by `@backstage/frontend-plugin-api`. The new `createFrontendPlugin` function doesn't accept apis anymore as apis are now extensions.
|
||||
|
||||
```ts title="my-plugin/src/alpha.ts"
|
||||
```ts title="my-plugin/src/alpha.tsx"
|
||||
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
||||
import { convertLegacyRouteRefs } from '@backstage/core-compat-api';
|
||||
|
||||
export default createFrontendPlugin({
|
||||
id: 'my-plugin',
|
||||
// bind all the extensions to the plugin
|
||||
/* highlight-next-line */
|
||||
extensions: [],
|
||||
extensions: [/* APIs will go here, but don't worry about those yet */],
|
||||
// convert old route refs to the new system
|
||||
/* highlight-next-line */
|
||||
routes: convertLegacyRouteRefs({
|
||||
@@ -52,20 +58,20 @@ The new `createFrontendPlugin` function doesn't accept apis anymore as apis are
|
||||
});
|
||||
```
|
||||
|
||||
The code above binds all the extensions to the plugin. _Important_: Make sure to export the plugin as default export of your package as a separate entrypoint, preferably `/alpha`, as suggested by the code snippet above. Make sure `src/alpha.ts` is exported in your `package.json`:
|
||||
The code above binds all the extensions to the plugin. _Important_: Make sure to export the plugin as default export of your package as a separate entrypoint, preferably `/alpha`, as suggested by the code snippet above. Make sure `src/alpha.tsx` is exported in your `package.json`:
|
||||
|
||||
```ts title="my-plugin/package.json"
|
||||
"exports": {
|
||||
".": "./src/index.ts",
|
||||
/* highlight-add-next-line */
|
||||
"./alpha": "./src/alpha.ts",
|
||||
"./alpha": "./src/alpha.tsx",
|
||||
"./package.json": "./package.json"
|
||||
},
|
||||
"typesVersions": {
|
||||
"*": {
|
||||
/* highlight-add-start */
|
||||
"alpha": [
|
||||
"src/alpha.ts"
|
||||
"src/alpha.tsx"
|
||||
],
|
||||
/* highlight-add-end */
|
||||
"package.json": [
|
||||
@@ -79,6 +85,8 @@ The code above binds all the extensions to the plugin. _Important_: Make sure to
|
||||
|
||||
Pages that were previously created using the `createRoutableExtension` extension function can be migrated to the new Frontend System using the `PageBlueprint` [extension blueprint](../architecture/23-extension-blueprints.md), exported by `@backstage/frontend-plugin-api`.
|
||||
|
||||
In the new system plugins provide more information than they used to. For example, the plugin is now responsible for providing the path for the page, rather than it being part of the app code.
|
||||
|
||||
For example, given the following page:
|
||||
|
||||
```ts
|
||||
@@ -91,7 +99,13 @@ export const FooPage = fooPlugin.provide(
|
||||
);
|
||||
```
|
||||
|
||||
it can be migrated as the following:
|
||||
and the following instruction in the plugin README:
|
||||
|
||||
```tsx
|
||||
<Route path="/foo" element={<FooPage />} />
|
||||
```
|
||||
|
||||
it can be migrated as the following, keeping in mind that you may need to switch from `.ts` to `.tsx`:
|
||||
|
||||
```tsx
|
||||
import { PageBlueprint } from '@backstage/frontend-plugin-api';
|
||||
@@ -102,15 +116,16 @@ import {
|
||||
|
||||
const fooPage = PageBlueprint.make({
|
||||
params: {
|
||||
// This is the path that was previously defined in the app code.
|
||||
// It's labelled as the default one because it can be changed via configuration.
|
||||
defaultPath: '/foo',
|
||||
// you can reuse the existing routeRef
|
||||
// by wrapping into the convertLegacyRouteRef.
|
||||
// You can reuse the existing routeRef by wrapping it with convertLegacyRouteRef.
|
||||
routeRef: convertLegacyRouteRef(rootRouteRef),
|
||||
// these inputs usually match the props required by the component.
|
||||
loader: ({ inputs }) =>
|
||||
loader: () =>
|
||||
import('./components/').then(m =>
|
||||
// The compatWrapper utility allows you to use the existing
|
||||
// legacy frontend utilities used internally by the components.
|
||||
// The compatWrapper utility allows you to keep using @backstage/core-plugin-api in the
|
||||
// implementation of the component and switch to @backstage/frontend-plugin-api later.
|
||||
compatWrapper(<m.FooPage />),
|
||||
),
|
||||
},
|
||||
@@ -119,7 +134,7 @@ const fooPage = PageBlueprint.make({
|
||||
|
||||
Then add the `fooPage` extension to the plugin:
|
||||
|
||||
```ts title="my-plugin/src/alpha.ts"
|
||||
```ts title="my-plugin/src/alpha.tsx"
|
||||
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
||||
|
||||
export default createFrontendPlugin({
|
||||
@@ -210,7 +225,7 @@ const exampleWorkApi = ApiBlueprint.make({
|
||||
|
||||
Finally, let's add the `exampleWorkApi` extension to the plugin:
|
||||
|
||||
```ts title="my-plugin/src/alpha.ts"
|
||||
```ts title="my-plugin/src/alpha.tsx"
|
||||
import { createFrontendPlugin } from '@backstage/frontend-plugin-api';
|
||||
|
||||
export default createFrontendPlugin({
|
||||
|
||||
@@ -416,8 +416,6 @@ In your front-end application, locate the `src` folder. We suggest creating the
|
||||
```tsx title="customIcons.tsx"
|
||||
import { SvgIcon, SvgIconProps } from '@material-ui/core';
|
||||
|
||||
import React from 'react';
|
||||
|
||||
export const ExampleIcon = (props: SvgIconProps) => (
|
||||
<SvgIcon {...props} viewBox="0 0 24 24">
|
||||
<path
|
||||
|
||||
@@ -111,7 +111,7 @@ If you opt for the second option of replacing the entire string, take care to no
|
||||
[Start the Backstage app](../index.md#2-run-the-backstage-app):
|
||||
|
||||
```shell
|
||||
yarn dev
|
||||
yarn start
|
||||
```
|
||||
|
||||
After the Backstage frontend launches, you should notice that nothing has changed. This is a good sign. If everything is setup correctly above, this means that the data is flowing from the demo data files directly into your database!
|
||||
|
||||
@@ -37,8 +37,6 @@ yarn --cwd packages/app add @backstage/plugin-home
|
||||
Inside your `packages/app` directory, create a new file where our new homepage component is going to live. Create `packages/app/src/components/home/HomePage.tsx` with the following initial code
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
|
||||
export const HomePage = () => (
|
||||
/* We will shortly compose a pretty homepage here. */
|
||||
<h1>Welcome to Backstage!</h1>
|
||||
@@ -156,7 +154,6 @@ contribute, check the
|
||||
> [Contributing documentation](https://github.com/backstage/backstage/blob/master/plugins/home/README.md#contributing)
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import Grid from '@material-ui/core/Grid';
|
||||
import { HomePageCompanyLogo } from '@backstage/plugin-home';
|
||||
|
||||
|
||||
@@ -116,11 +116,11 @@ If this fails on the `yarn install` step, it's likely that you will need to inst
|
||||
|
||||
## 2. Run the Backstage app
|
||||
|
||||
Your Backstage app is fully installed and ready to be run! Now that the installation is complete, you can go to the application directory and start the app using the `yarn dev` command. The `yarn dev` command will run both the frontend and backend as separate processes (named `[0]` and `[1]`) in the same window.
|
||||
Your Backstage app is fully installed and ready to be run! Now that the installation is complete, you can go to the application directory and start the app using the `yarn start` command. The `yarn start` command will run both the frontend and backend as separate processes (named `[0]` and `[1]`) in the same window.
|
||||
|
||||
```bash
|
||||
cd my-backstage-app # your app name
|
||||
yarn dev
|
||||
yarn start
|
||||
```
|
||||
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ You should have already [have a standalone app](./index.md) and completed the Gi
|
||||
|
||||
## 1. Login to Backstage
|
||||
|
||||
Run your Backstage app with `yarn dev`. Navigate to `http://localhost:3000`.
|
||||
Run your Backstage app with `yarn start`. Navigate to `http://localhost:3000`.
|
||||
|
||||
If you're not already logged in, you should see a login screen like this,
|
||||
|
||||
|
||||
@@ -187,7 +187,7 @@ To install custom rules in a plugin, we need to use the [`PermissionsRegistrySer
|
||||
backend.add(import('./extensions/catalogPermissionRules'));
|
||||
```
|
||||
|
||||
5. Now when you run you Backstage instance - `yarn dev` - the rule will be added to the catalog plugin.
|
||||
5. Now when you run you Backstage instance - `yarn start` - the rule will be added to the catalog plugin.
|
||||
|
||||
The updated policy will allow catalog entity resource permissions if any of the following are true:
|
||||
|
||||
|
||||
@@ -103,10 +103,10 @@ Now lets test end to end that the permissions framework is setup and configured
|
||||
enabled: true
|
||||
```
|
||||
|
||||
2. Now run `yarn dev`, Backstage should load up in your browser
|
||||
2. Now run `yarn start`, Backstage should load up in your browser
|
||||
3. You should see that you have entities in your Catalog, pretty simple
|
||||
4. Let's change this line in our Test Permission Policy `return { result: AuthorizeResult.ALLOW };` to be `return { result: AuthorizeResult.DENY };`
|
||||
5. Run `yarn dev` once again, Backstage should load up in your browser
|
||||
5. Run `yarn start` once again, Backstage should load up in your browser
|
||||
6. This time you should not see any entities in your Catalog, if you do then something went wrong along the way and you'll need to review the steps above
|
||||
7. Revert the change we made in step 4 so that the line looks like this: `return { result: AuthorizeResult.ALLOW };`
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ And then select `frontend-plugin`.
|
||||
This will create a new Backstage Plugin based on the ID that was provided. It
|
||||
will be built and added to the Backstage App automatically.
|
||||
|
||||
> If the Backstage App is already running (with `yarn start` or `yarn dev`) you
|
||||
> If the Backstage App is already running (with `yarn start`) you
|
||||
> should be able to see the default page for your new plugin directly by
|
||||
> navigating to `http://localhost:3000/my-plugin`.
|
||||
|
||||
|
||||
@@ -245,7 +245,7 @@ You can also check out the documentation on [how to test Backstage plugin module
|
||||
|
||||
#### 9. Running the collator locally
|
||||
|
||||
Run `yarn dev` in the root folder of your Backstage project and look for logs like these:
|
||||
Run `yarn start` in the root folder of your Backstage project and look for logs like these:
|
||||
|
||||
```sh
|
||||
[backend]: YYYY-MM-DDTHH:MM:SS.000Z search info Task worker starting: search_index_faq_snippets, {"version":2,"cadence":"PT10M","initialDelayDuration":"PT3S","timeoutAfterDuration":"PT15M"} task=search_index_faq_snippets
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -48,12 +48,14 @@ help [command] display help for command
|
||||
The `repo` command category, `yarn backstage-cli repo --help`:
|
||||
|
||||
```text
|
||||
build [options] Build packages in the project, excluding bundled app and backend packages.
|
||||
lint [options] Lint all packages in the project
|
||||
clean Delete cache and output directories
|
||||
list-deprecations [options] List deprecations
|
||||
test [options] Run tests, forwarding args to Jest, defaulting to watch mode
|
||||
help [command] display help for command
|
||||
start [options] [packageName...] Starts packages in the repo for local development
|
||||
build [options] Build packages in the project, excluding bundled app and backend packages.
|
||||
test [options] Run tests, forwarding args to Jest, defaulting to watch mode
|
||||
lint [options] Lint all packages in the project
|
||||
fix [options] Automatically fix packages in the project
|
||||
clean Delete cache and output directories
|
||||
list-deprecations [options] List deprecations
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
The `migrate` command category, `yarn backstage-cli migrate --help`:
|
||||
@@ -67,6 +69,31 @@ react-router-deps Migrates the react-router dependencies for all packages to
|
||||
help [command] display help for command
|
||||
```
|
||||
|
||||
## repo start
|
||||
|
||||
Start a set of packages in the project for local development. If no explicit packages are listed via arguments or options, packages will instead be selected based on their [package role](./02-build-system.md#package-roles). If a single set of frontend and/or backend packages are found, they will be started. If there are multiple matches the directories 'packages/app' and 'packages/backend' will be preferred. If no matches are found the command will fall back to expecting a single plugin frontend and/or backend package to start instead.
|
||||
|
||||
Any `--config` options in the `start` script in `package.json` of the selected packages will be picked up and used, unless a `--config` option is provided to this command, in which case it will be used instead.
|
||||
|
||||
Any `--require` option in the `start` script in `package.json` of the selected backend package will be picked up and used.
|
||||
|
||||
```text
|
||||
Usage: backstage-cli repo start [options] [packageNameOrPath...]
|
||||
|
||||
Starts packages in the repo for local development
|
||||
|
||||
Arguments:
|
||||
packageNameOrPath Run the specified packages instead of the defaults.
|
||||
|
||||
Options:
|
||||
--plugin <pluginId> Start the dev entry-point for any matching plugin package in the repo (default: [])
|
||||
--config <path> Config files to load instead of app-config.yaml (default: [])
|
||||
--inspect [host] Enable debugger in Node.js environments. Applies to backend package only
|
||||
--inspect-brk [host] Enable debugger in Node.js environments, breaking before code starts. Applies to backend package only
|
||||
--require <path...> Add a --require argument to the node process. Applies to backend package only
|
||||
--link <path> Link an external workspace for module resolution
|
||||
```
|
||||
|
||||
## repo build
|
||||
|
||||
Builds all packages in the project, excluding bundled packages by default, i.e. ones
|
||||
|
||||
@@ -19,7 +19,7 @@ Changing the level can be done by setting the `LOG_LEVEL` environment variable.
|
||||
For example, to turn on debug logs when running the app locally, you can run:
|
||||
|
||||
```shell
|
||||
LOG_LEVEL=debug yarn dev
|
||||
LOG_LEVEL=debug yarn start
|
||||
```
|
||||
|
||||
The resulting log should now have more information available for debugging:
|
||||
|
||||
@@ -60,6 +60,6 @@ See more command options in the AutoCannon documentation.
|
||||
Profiling the frontend can be done by using the `React DevTools` extension for Chrome or Firefox.
|
||||
The extension is available for download from the Chrome Web Store or the Firefox Add-ons website.
|
||||
|
||||
To start profiling, start the application with `yarn dev` and open inspector in the browser. In the
|
||||
To start profiling, start the application with `yarn start` and open inspector in the browser. In the
|
||||
`Profiler` tab (far to the right), click the `Start profiling` button to start recording. After
|
||||
you have recorded some data by navigating through the page, click the `Stop profiling` button to stop the recording.
|
||||
|
||||
@@ -32,7 +32,6 @@ With that, Backstage's cli and backend will detect public entry point and serve
|
||||
2. This file is the public entry point for your application, and it should only contain what unauthenticated users should see:
|
||||
|
||||
```tsx title="in packages/app/src/index-public-experimental.tsx"
|
||||
import React from 'react';
|
||||
import ReactDOM from 'react-dom/client';
|
||||
import { createApp } from '@backstage/app-defaults';
|
||||
import { AppRouter } from '@backstage/core-app-api';
|
||||
|
||||
@@ -134,7 +134,6 @@ changes, let's start by wiping this component clean.
|
||||
1. Replace everything in the file with the following:
|
||||
|
||||
```tsx
|
||||
import React from 'react';
|
||||
import useAsync from 'react-use/lib/useAsync';
|
||||
import Alert from '@material-ui/lab/Alert';
|
||||
import { Table, TableColumn, Progress } from '@backstage/core-components';
|
||||
|
||||
@@ -50,7 +50,6 @@ To switch a project to React 18, there are generally three changes that need to
|
||||
|
||||
```tsx title="packages/app/src/index.tsx"
|
||||
import '@backstage/cli/asset-types';
|
||||
import React from 'react';
|
||||
// highlight-remove-next-line
|
||||
import ReactDOM from 'react-dom';
|
||||
// highlight-add-next-line
|
||||
|
||||
@@ -62,7 +62,7 @@ For local development, you can add the required flag in your `packages/backend/p
|
||||
...
|
||||
```
|
||||
|
||||
You can now start your Backstage instance as usual, using `yarn dev`.
|
||||
You can now start your Backstage instance as usual, using `yarn start`.
|
||||
|
||||
## Production Setup
|
||||
|
||||
|
||||
Reference in New Issue
Block a user