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

Merge pull request #5353 from backstage/rugvip/plugins-docs

Browse Source 
docs,READMEs: updates for composability changes
This commit is contained in:
Patrik Oldsberg
2021-04-27 17:47:13 +02:00
committed by GitHub
parent 9a69a3877e e5d4cd4dc8
commit 61fdfd70a3
26 changed files with 194 additions and 317 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/api-docs/README.md
+2 -12
View File
@@ -33,17 +33,7 @@ To link that a component provides or consumes an API, see the [`providesApis`](h
yarn add @backstage/plugin-api-docs
```
2. Add the plugin to the app:
```ts
// packages/app/src/plugins.ts
export { apiDocsPlugin } from '@backstage/plugin-api-docs';
```
<Route path="/api-docs" element={<ApiExplorerPage />} />
3. Register the `ApiExplorerPage` at the `/api-docs` path:
2. Add the `ApiExplorerPage` extension to the app:
```tsx
// packages/app/src/App.tsx
@@ -53,7 +43,7 @@ import { ApiExplorerPage } from '@backstage/plugin-api-docs';
<Route path="/api-docs" element={<ApiExplorerPage />} />;
```
4. Add one of the provided widgets to the EntityPage:
3. Add one of the provided widgets to the EntityPage:
```tsx
// packages/app/src/components/catalog/EntityPage.tsx
plugins/bitrise/README.md
+14 -20
View File
@@ -8,36 +8,30 @@ Welcome to the Bitrise plugin!
## Installation
```sh
# The plugin must be added in the app package
$ cd packages/app
$ yarn add @backstage/plugin-bitrise
```
Then make sure to export the plugin in your app's [`plugins.ts`](https://github.com/backstage/backstage/blob/master/packages/app/src/plugins.ts) to enable the plugin:
```js
export { bitrisePlugin } from '@backstage/plugin-bitrise';
```
Bitrise Plugin exposes an "Entity Tab Content" component `EntityBitriseContent`. You can include it in the [`EntityPage.tsx`](https://github.com/backstage/backstage/blob/master/packages/app/src/components/catalog/EntityPage.tsx)`:
Bitrise Plugin exposes an entity tab component named `EntityBitriseContent`. You can include it in the
[`EntityPage.tsx`](https://github.com/backstage/backstage/blob/master/packages/app/src/components/catalog/EntityPage.tsx)`:
```tsx
// At the top imports
import { EntityBitriseContent } from '@backstage/plugin-bitrise';
// Inside `WebsiteEntityPage` component
<EntityPageLayout.Content
path="/bitrise"
title="Bitrise"
element={
<Grid container spacing={3}>
<Grid item xs={12}>
<EntityBitrisePage />
</Grid>
</Grid>
}
/>;
// Farther down at the website declaration
const websiteEntityPage = (
<EntityLayoutWrapper>
{/* Place the following section where you want the tab to appear */}
<EntityLayout.Route path="/bitrise" title="Bitrise">
<EntityBitriseContent />
</EntityLayout.Route>
```
Now your plugin should be visible in the entity page, however in a state with a missing `bitrise.io/app` annotation.
Now your plugin should be visible as a tab at the top of the entity pages,
specifically for components that are of the type `website`.
However, it warns of a missing `bitrise.io/app` annotation.
Add the annotation to your component [catalog-info.yaml](https://github.com/backstage/backstage/blob/master/catalog-info.yaml) as shown in the highlighted example below:
plugins/catalog-import/README.md
+1 -9
View File
@@ -23,15 +23,7 @@ Some features are not yet available for all supported Git providers.
yarn add @backstage/plugin-catalog-import
```
2. Add the plugin to the app:
```ts
// packages/app/src/plugins.ts
export { catalogImportPlugin } from '@backstage/plugin-catalog-import';
```
3. Register the `CatalogImportPage` at the `/catalog-import` path:
2. Add the `CatalogImportPage` extension to the app:
```tsx
// packages/app/src/App.tsx
plugins/circleci/README.md
+13 -17
View File
@@ -13,26 +13,22 @@ Website: [https://circleci.com/](https://circleci.com/)
yarn add @backstage/plugin-circleci
```
2. Add plugin itself:
2. Add the `EntityCircleCIContent` extension to the entity page in the app:
```js
// packages/app/src/plugins.ts
export { plugin as Circleci } from '@backstage/plugin-circleci';
```
3. Register the plugin router:
```jsx
```tsx
// packages/app/src/components/catalog/EntityPage.tsx
import { EntityCircleCIContent } from '@backstage/plugin-circleci';
import { Router as CircleCIRouter } from '@backstage/plugin-circleci';
// Then somewhere inside <EntityPageLayout>
<EntityPageLayout.Content
path="/ci-cd/*"
title="CI/CD"
element={<CircleCIRouter />}
/>;
// ...
const serviceEntityPage = (
<EntityPageLayout>
...
<EntityLayout.Route path="/circle-ci" title="Circle CI">
<EntityCircleCIContent />
</EntityLayout.Route>
...
</EntityPageLayout>
);
```
4. Add proxy config:
plugins/cost-insights/README.md
+10 -4
View File
@@ -51,11 +51,17 @@ export const apis = [
];
```
4. Add cost-insights to your Backstage plugins.
4. Add the `CostInsightsPage` extension to your `App.tsx`:
```ts
// packages/app/src/plugins.ts
export { plugin as CostInsights } from '@backstage/plugin-cost-insights';
```tsx
// packages/app/src/App.tsx
import { CostInsightsPage } from '@backstage/plugin-cost-insights';
<FlatRoutes>
...
<Route path="/cost-insights" element={<CostInsightsPage />} />
...
</FlatRoutes>;
```
5. Add Cost Insights to your app Sidebar.
plugins/explore/README.md
+2 -8
View File
@@ -5,13 +5,7 @@ This plugin helps to visualize the domains and tools in your ecosystem.
## Getting started
To install the plugin, include the following import your `plugins.ts`:
```typescript
export { explorePlugin } from '@backstage/plugin-explore';
```
Register and bind the route in `App.tsx`:
To install the plugin, add and bind the route in `App.tsx`:
```typescript
import { ExplorePage, explorePlugin } from '@backstage/plugin-explore';
@@ -30,7 +24,7 @@ bindRoutes({ bind }) {
<Route path="/explore" element={<ExplorePage />} />
```
Add a link to the sidebar in `Root.tsx`:
And add a link to the sidebar in `Root.tsx`:
```typescript
import LayersIcon from '@material-ui/icons/Layers';
plugins/fossa/README.md
+4 -12
View File
@@ -14,15 +14,7 @@ The FOSSA Plugin displays code statistics from [FOSSA](https://fossa.com/).
yarn add @backstage/plugin-fossa
```
2. Add plugin to the app:
```js
// packages/app/src/plugins.ts
export { fossaPlugin } from '@backstage/plugin-fossa';
```
3. Add the `EntityFossaCard` to the EntityPage:
2. Add the `EntityFossaCard` to the EntityPage:
```jsx
// packages/app/src/components/catalog/EntityPage.tsx
@@ -40,7 +32,7 @@ const OverviewContent = ({ entity }: { entity: Entity }) => (
);
```
4. Add the proxy config:
3. Add the proxy config:
```yaml
# app-config.yaml
@@ -57,9 +49,9 @@ fossa:
organizationId: <your-fossa-organization-id>
```
5. Get an api-token and provide `FOSSA_AUTH_HEADER` as env variable (https://app.fossa.com/account/settings/integrations/api_tokens)
4. Get an api-token and provide `FOSSA_AUTH_HEADER` as env variable (https://app.fossa.com/account/settings/integrations/api_tokens)
6. Add the `fossa.io/project-name` annotation to your catalog-info.yaml file:
5. Add the `fossa.io/project-name` annotation to your catalog-info.yaml file:
```yaml
apiVersion: backstage.io/v1alpha1
plugins/github-actions/README.md
+18 -6
View File
@@ -35,17 +35,29 @@ TBD
### Standalone app requirements
If you didn't clone this repo you have to do some extra work.
1. Add plugin API to your Backstage instance:
1. Install the plugin dependency in your Backstage app package:
```bash
cd packages/app
yarn add @backstage/plugin-github-actions
```
```js
// packages/app/src/plugins.ts
export { plugin as GithubActions } from '@backstage/plugin-github-actions';
2. Add to the app `EntityPage` component:
```tsx
// packages/app/src/components/catalog/EntityPage.tsx
import { EntityGithubActionsContent } from '@backstage/plugin-github-actions';
// ...
const serviceEntityPage = (
<EntityPageLayout>
...
<EntityLayout.Route path="/github-actions" title="GitHub Actions">
<EntityGithubActionsContent />
</EntityLayout.Route>
...
</EntityPageLayout>
);
```
2. Run the app with `yarn start` and the backend with `yarn --cwd packages/backend start`, navigate to `/github-actions/`.
plugins/github-deployments/README.md
+2 -10
View File
@@ -18,15 +18,7 @@ The GitHub Deployments Plugin displays recent deployments from GitHub.
yarn add @backstage/plugin-github-deployments
```
2. Add the plugin to the app
```typescript
// packages/app/src/plugins.ts
export { githubDeploymentsPlugin as GithubDeploymentsPlugin } from '@backstage/plugin-github-deployments';
```
3. Add the `EntityGithubDeploymentsCard` to the EntityPage:
2. Add the `EntityGithubDeploymentsCard` to the EntityPage:
```typescript
// packages/app/src/components/catalog/EntityPage.tsx
@@ -44,7 +36,7 @@ const OverviewContent = () => (
);
```
4. Add the `github.com/project-slug` annotation to your `catalog-info.yaml` file:
3. Add the `github.com/project-slug` annotation to your `catalog-info.yaml` file:
```yaml
apiVersion: backstage.io/v1alpha1
plugins/graphiql/README.md
+4 -9
View File
@@ -16,18 +16,13 @@ cd packages/app
yarn add @backstage/plugin-graphiql
```
```diff
# in packages/app/src/plugins.ts
+export { plugin as GraphiQL } from '@backstage/plugin-graphiql';
```
```diff
# in packages/app/src/App.tsx
+import { Router as GraphiQLRouter } from '@backstage/plugin-graphiql';
+import { GraphiQLPage } from '@backstage/plugin-graphiql';
const AppRoutes = () => (
<Routes>
+ <Route path="/graphiql" element={<GraphiQLRouter />} />
const routes = (
<FlatRoutes>
+ <Route path="/graphiql" element={<GraphiQLPage />} />
```
### Adding GraphQL endpoints
plugins/jenkins/README.md
+15 -4
View File
@@ -14,11 +14,22 @@ Website: [https://jenkins.io/](https://jenkins.io/)
yarn add @backstage/plugin-jenkins
```
2. Add plugin:
2. Add the `EntityJenkinsContent` extension to the entity page in the app:
```js
// packages/app/src/plugins.ts
export { plugin as Jenkins } from '@backstage/plugin-jenkins';
```tsx
// packages/app/src/components/catalog/EntityPage.tsx
import { EntityJenkinsContent } from '@backstage/plugin-circleci';
// ...
const serviceEntityPage = (
<EntityPageLayout>
...
<EntityLayout.Route path="/jenkins" title="Jenkins">
<EntityJenkinsContent />
</EntityLayout.Route>
...
</EntityPageLayout>
);
```
3. Add proxy configuration to `app-config.yaml`
plugins/lighthouse/README.md
+5 -14
View File
@@ -31,26 +31,17 @@ When you have an instance running that Backstage can hook into, first install th
$ yarn add @backstage/plugin-lighthouse
```
Then make sure to export the plugin in
your app's [`plugins.ts`](https://github.com/backstage/backstage/blob/master/packages/app/src/plugins.ts)
to enable the plugin:
```js
export { plugin as LighthousePlugin } from '@backstage/plugin-lighthouse';
```
Modify your app routes in `App.tsx` to include the Router component exported from the plugin, for example:
Modify your app routes in `App.tsx` to include the `LighthousePage` component exported from the plugin, for example:
```tsx
// At the top imports
import { Router as LighthouseRouter } from '@backstage/plugin-lighthouse';
import { LighthousePage } from '@backstage/plugin-lighthouse';
// Inside App component
<Routes>
<FlatRoutes>
// ...
<Route path="/lighthouse/*" element={<LighthouseRouter />} />
<Route path="/lighthouse" element={<LighthousePage />} />
// ...
</Routes>;
</FlatRoutes>;
```
Then configure the `lighthouse-audit-service` URL in your [`app-config.yaml`](https://github.com/backstage/backstage/blob/master/app-config.yaml).
plugins/lighthouse/src/components/Intro/index.tsx
+2 -9
View File
@@ -49,19 +49,12 @@ When you have an instance running that Backstage can hook into, first install th
$ yarn add @backstage/plugin-lighthouse
\`\`\`
Then make sure to export the plugin in your app's [\`plugins.ts\`](https://github.com/backstage/backstage/blob/master/packages/app/src/plugins.ts) to enable the plugin:
Modify your app routes in \`App.tsx\` to include the \`LighthousePage\` component exported from the plugin, for example:
\`\`\`js
export { plugin as LighthousePlugin } from '@backstage/plugin-lighthouse';
\`\`\`
Modify your app routes in \`App.tsx\` or \`App.jsx\` to include the Router component exported from the plugin, for example:
\`\`\`js
\`\`\`tsx
// At the top imports
import { LighthousePage } from '@backstage/plugin-lighthouse';
// Inside App component
<FlatRoutes>
// ...
<Route path="/lighthouse" element={<LighthousePage />} />
plugins/pagerduty/README.md
-6
View File
@@ -22,12 +22,6 @@ Install the plugin:
yarn add @backstage/plugin-pagerduty
```
Add it to the app in `plugins.ts`:
```ts
export { plugin as Pagerduty } from '@backstage/plugin-pagerduty';
```
Add it to the `EntityPage.tsx`:
```ts
plugins/register-component/README.md
+11 -56
View File
@@ -16,69 +16,24 @@ When installed it is accessible on [localhost:3000/register-component](localhost
## Standalone setup
0. Install plugin and its dependency `plugin-catalog`
1. Install plugin and its dependency `plugin-catalog`
```bash
yarn add @backstage/plugin-register-component -W
yarn add @backstage/plugin-catalog -W
cd packages/app
yarn add @backstage/plugin-register-component
```
1. Add dependencies to the active plugins list
2. Add the `RegisterComponentPage` extension to your `App.tsx`:
```typescript
// packages/app/src/plugins.ts
export { plugin as RegisterComponent } from '@backstage/plugin-register-component';
export { plugin as CatalogPlugin } from '@backstage/plugin-catalog';
```
2. Create `packages/app/src/apis.ts` and register all the needed plugins
```typescript
import {
alertApiRef,
AlertApiForwarder,
ApiRegistry,
ConfigApi,
errorApiRef,
ErrorApiForwarder,
ErrorAlerter,
} from '@backstage/core';
import { catalogApiRef, CatalogClient } from '@backstage/plugin-catalog';
export const apis = (config: ConfigApi) => {
const backendUrl = config.getString('backend.baseUrl');
const builder = ApiRegistry.builder();
const alertApi = builder.add(alertApiRef, new AlertApiForwarder());
const errorApi = builder.add(
errorApiRef,
new ErrorAlerter(alertApi, new ErrorApiForwarder()),
);
builder.add(
catalogApiRef,
new CatalogClient({
apiOrigin: backendUrl,
basePath: '/catalog',
}),
);
return builder.build();
};
```
3. Pass `apis` to createApp
```typescript
```tsx
// packages/app/src/App.tsx
import { apis } from './apis';
import { RegisterComponentPage } from '@backstage/plugin-cost-insights';
const app = createApp({
apis,
plugins: Object.values(plugins),
});
<FlatRoutes>
...
<Route path="/register-component" element={<RegisterComponentPage />} />
...
</FlatRoutes>;
```
## Running
plugins/rollbar/README.md
+12 -20
View File
@@ -12,33 +12,25 @@ Website: [https://rollbar.com/](https://rollbar.com/)
yarn add @backstage/plugin-rollbar
```
3. Add plugin to the list of plugins:
3. Add to the app `EntityPage` component:
```ts
// packages/app/src/plugins.ts
export { plugin as Rollbar } from '@backstage/plugin-rollbar';
```
4. Add to the app `EntityPage` component:
```ts
```tsx
// packages/app/src/components/catalog/EntityPage.tsx
import { Router as RollbarRouter } from '@backstage/plugin-rollbar';
import { EntityRollbarContent } from '@backstage/plugin-rollbar';
// ...
const ServiceEntityPage = ({ entity }: { entity: Entity }) => (
const serviceEntityPage = (
<EntityPageLayout>
// ...
<EntityPageLayout.Content
path="/rollbar"
title="Errors"
element={<RollbarRouter entity={entity} />}
/>
...
<EntityLayout.Route path="/rollbar" title="Rollbar">
<EntityRollbarContent />
</EntityLayout.Route>
...
</EntityPageLayout>
);
```
5. Setup the `app.config.yaml` and account token environment variable
4. Setup the `app-config.yaml` and account token environment variable
```yaml
# app.config.yaml
@@ -48,7 +40,7 @@ rollbar:
accountToken: ${ROLLBAR_ACCOUNT_TOKEN}
```
6. Annotate entities with the rollbar project slug
5. Annotate entities with the rollbar project slug
```yaml
# pump-station-catalog-component.yaml
@@ -60,7 +52,7 @@ metadata:
rollbar.com/project-slug: project-name
```
7. Run app with `yarn start` and navigate to `/rollbar` or a catalog entity
6. Run app with `yarn start` and navigate to `/rollbar` or a catalog entity
## Features
plugins/sentry/README.md
+15 -25
View File
@@ -14,53 +14,43 @@ The Sentry Plugin displays issues from [Sentry](https://sentry.io).
yarn add @backstage/plugin-sentry
```
2. Add plugin to the app:
```js
// packages/app/src/plugins.ts
export { plugin as Sentry } from '@backstage/plugin-sentry';
```
3. Add the `SentryIssuesWidget` to the EntityPage:
2. Add the `EntitySentryCard` to the EntityPage:
```jsx
// packages/app/src/components/catalog/EntityPage.tsx
import { SentryIssuesWidget } from '@backstage/plugin-sentry';
import { EntitySentryCard } from '@backstage/plugin-sentry';
const OverviewContent = ({ entity }: { entity: Entity }) => (
const overviewContent = (
<Grid container spacing={3} alignItems="stretch">
// ...
<Grid item xs={12} sm={6} md={4}>
<SentryIssuesWidget entity={entity} />
<EntitySentryCard />
</Grid>
// ...
</Grid>
);
```
> You can also import a `Router` if you want to have a dedicated sentry page:
> You can also import the full-page `EntitySentryContent` extension if you want to have a dedicated sentry page:
>
> ```tsx
> // packages/app/src/components/catalog/EntityPage.tsx
>
> import { Router as SentryRouter } from '@backstage/plugin-sentry';
> import { EntitySentryContent } from '@backstage/plugin-sentry';
>
> const ServiceEntityPage = ({ entity }: { entity: Entity }) => (
> <EntityPageLayout>
> const serviceEntityPage = (
> <EntityLayout>
> // ...
> <EntityPageLayout.Content
> path="/sentry"
> title="Sentry"
> element={<SentryRouter entity={entity} />}
> />
> <EntityLayout.Route path="/sentry" title="Sentry">
> <EntitySentryContent />
> </EntityLayout.Route>
> // ...
> </EntityPageLayout>
> </EntityLayout>
> );
> ```
4. Add the proxy config:
3. Add the proxy config:
```yaml
# app-config.yaml
@@ -76,9 +66,9 @@ sentry:
organization: <your-organization>
```
5. Create a new internal integration with the permissions `Issues & Events: Read` (https://docs.sentry.io/product/integrations/integration-platform/) and provide it as `SENTRY_TOKEN` as env variable.
4. Create a new internal integration with the permissions `Issues & Events: Read` (https://docs.sentry.io/product/integrations/integration-platform/) and provide it as `SENTRY_TOKEN` as env variable.
6. Add the `sentry.io/project-slug` annotation to your catalog-info.yaml file:
5. Add the `sentry.io/project-slug` annotation to your catalog-info.yaml file:
```yaml
apiVersion: backstage.io/v1alpha1
plugins/sonarqube/README.md
+5 -12
View File
@@ -13,14 +13,7 @@ The SonarQube Plugin displays code statistics from [SonarCloud](https://sonarclo
yarn add @backstage/plugin-sonarqube
```
2. Add plugin to the app:
```js
// packages/app/src/plugins.ts
export { plugin as SonarQube } from '@backstage/plugin-sonarqube';
```
3. Add the `EntitySonarQubeCard` to the EntityPage:
2. Add the `EntitySonarQubeCard` to the EntityPage:
```diff
// packages/app/src/components/catalog/EntityPage.tsx
@@ -40,7 +33,7 @@ export { plugin as SonarQube } from '@backstage/plugin-sonarqube';
);
```
4. Add the proxy config:
3. Add the proxy config:
Provide a method for your Backstage backend to get to your SonarQube API end point. Add configuration to your `app-config.yaml` file depending on the product you use.
@@ -77,16 +70,16 @@ sonarQube:
baseUrl: https://your.sonarqube.instance.com
```
5. Get and provide `SONARQUBE_AUTH` as an env variable (https://sonarcloud.io/account/security or https://docs.sonarqube.org/latest/user-guide/user-token/)
4. Get and provide `SONARQUBE_AUTH` as an env variable (https://sonarcloud.io/account/security or https://docs.sonarqube.org/latest/user-guide/user-token/)
6. Run the following commands in the root folder of the project to install and compile the changes.
5. Run the following commands in the root folder of the project to install and compile the changes.
```yaml
yarn install
yarn tsc
```
7. Add the `sonarqube.org/project-key` annotation to the `catalog-info.yaml` file of the target repo for which code quality analysis is needed.
6. Add the `sonarqube.org/project-key` annotation to the `catalog-info.yaml` file of the target repo for which code quality analysis is needed.
```yaml
apiVersion: backstage.io/v1alpha1