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

Merge branch 'master' of github.com:spotify/backstage into shmidt-i/app-catalog-tabs-routes-everything-is-connected

Browse Source
This commit is contained in:
Ivan Shmidt
2020-08-31 23:21:23 +02:00
parent 713060d1f3 3305bac3b1
commit 68474750db
315 changed files with 5576 additions and 2578 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins/add-to-marketplace.md
+23
View File
@@ -0,0 +1,23 @@
---
id: add-to-marketplace
title: Add to Marketplace
---
## Adding a Plugin to the Marketplace
To add a new plugin to the [plugin marketplace](https://backstage.io/plugins)
create a file in `data/plugins` with your plugin's information. Example:
```yaml
---
title: Your Plugin
author: Your Name
authorUrl: # A link to information about the author E.g. Company url, github user profile, etc
category: Monitoring # A single category e.g. CI, Machine Learning, Services, Monitoring
description: A brief description of the plugin. # Max 170 characters
documentation: # A link to your documentation E.g. Your github README
iconUrl: # Used as the src attribute for your logo.
# You can provide an external url or add your logo under static/img and provide a path
# relative to static/ e.g. img/my-logo.png
npmPackageName: # Your npm package name E.g. '@backstage/plugin-<etc>' quotes are required
```
docs/plugins/call-existing-api.md
+3 -8
View File
@@ -71,11 +71,7 @@ Example:
```yaml
# In app-config.yaml
proxy:
'/frobs':
target: 'http://api.frobsco.com/v1'
changeOrigin: true
pathRewrite:
'^/proxy/frobs/': '/'
'/frobs': http://api.frobsco.com/v1
```
```ts
@@ -86,9 +82,8 @@ fetch(`${backendUrl}/proxy/frobs/list`)
.then(payload => setFrobs(payload as Frob[]));
```
The proxy is powered by the `http-proxy-middleware` package, and supports all of
its
[configuration options](https://github.com/chimurai/http-proxy-middleware#options).
The proxy is powered by the `http-proxy-middleware` package. See
[Proxying](proxying.md) for a full description of its configuration options.
Internally at Spotify, the proxy option has been the overwhelmingly most popular
choice for plugin makers. Since we have DNS based service discovery in place and
docs/plugins/create-a-plugin.md
+5 -13
View File
@@ -15,20 +15,16 @@ dependencies, then run the following on your command line (invoking the
yarn create-plugin
```
<p align='center'>
<img src='https://github.com/spotify/backstage/raw/master/docs/getting-started/create-plugin_output.png' width='600' alt='create plugin'>
</p>
![](../assets/getting-started/create-plugin_output.png)
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 `yarn start` is already running you should be able to see the default page
for your new plugin directly by navigating to
`http://localhost:3000/my-plugin`._
> If `yarn start` is already running you should be able to see the default page
> for your new plugin directly by navigating to
> `http://localhost:3000/my-plugin`.
<p align='center'>
<img src='https://github.com/spotify/backstage/raw/master/docs/plugins/my-plugin_screenshot.png' width='600' alt='my plugin'>
</p>
![](../assets/my-plugin_screenshot.png)
You can also serve the plugin in isolation by running `yarn start` in the plugin
directory. Or by using the yarn workspace command, for example:
@@ -40,7 +36,3 @@ yarn workspace @backstage/plugin-welcome start # Also supports --check
This method of serving the plugin provides quicker iteration speed and a faster
startup and hot reloads. It is only meant for local development, and the setup
for it can be found inside the plugin's `dev/` directory.
[Next Step - Structure of a plugin](structure-of-a-plugin.md)
[Back to Getting Started](../README.md)
docs/plugins/index.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
id: index
title: Intro
title: Intro to plugins
---
Backstage is a single-page application composed of a set of plugins.
docs/plugins/plugin-development.md
+3 -19
View File
@@ -1,6 +1,6 @@
---
id: plugin-development
title: Plugin Development in Backstage
title: Plugin Development
---
Backstage plugins provide features to a Backstage App.
@@ -10,28 +10,12 @@ type of content. Plugins all use a common set of platform APIs and reusable UI
components. Plugins can fetch data from external sources using the regular
browser APIs or by depending on external modules to do the work.
<!-- MOVED TO create-a-plugin.md ## Creating a new plugin
On your command line, invoke the `backstage-cli` to create a new plugin:
```bash
yarn create-plugin
```
![](create-plugin_output.png)
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 `yarn start` is already running you should be able to see the default page for your new
plugin directly by navigating to `http://localhost:3000/my-plugin`.*
![](my-plugin_screenshot.png) -->
## Developing guidelines
- Consider writing plugins in `TypeScript`.
- Plan the directory structure of your plugin so that it becomes easy to manage.
- Prefer using the Backstage components, otherwise go with
[Material-UI](https://material-ui.com/).
- Prefer using the [Backstage components](https://backstage.io/storybook),
otherwise go with [Material-UI](https://material-ui.com/).
- Check out the shared Backstage APIs before building a new one.
## Plugin concepts / API
docs/plugins/proxying.md
+70 -1
View File
@@ -3,4 +3,73 @@ id: proxying
title: Proxying
---
## TODO
## Overview
The Backstage backend comes packaged with a basic HTTP proxy, that can aid in
reaching backend service APIs from frontend plugin code. See
[Call Existing API](call-existing-api.md) for a description of when the proxy
can be the best choice for communicating with an API.
## Getting Started
The plugin is already added to a default Backstage project.
In `packages/backend/src/index.ts`:
```ts
const proxyEnv = useHotMemoize(module, () => createEnv('proxy'));
const service = createServiceBuilder(module)
.loadConfig(configReader)
/** ... other routers ... */
.addRouter('/proxy', await proxy(proxyEnv, '/proxy'));
```
## Configuration
Configuration for the proxy plugin lives under a `proxy` root key of your
`app-config.yaml` file.
Example:
```yaml
# in app-config.yaml
proxy:
'/simple-example': http://simple.example.com:8080
'/larger-example/v1':
target: http://larger.example.com:8080/svc.v1
headers:
Authorization:
$secret:
env: EXAMPLE_AUTH_HEADER
```
Each key under the proxy configuration entry is a route to match, below the
prefix that the proxy plugin is mounted on. It must start with a slash. For
example, if the backend mounts the proxy plugin as `/proxy`, the above
configuration will lead to the proxy acting on backend requests to
`/proxy/simple-example/...` and `/proxy/larger-example/v1/...`.
The value inside each route is either a simple URL string, or an object on the
format accepted by
[http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware).
If the value is a string, it is assumed to correspond to:
```yaml
target: <the string>
changeOrigin: true
pathRewrite:
'^<url prefix><the string>/': '/'
```
When the target is an object, it is given verbatim to `http-proxy-middleware`
except with the following caveats for convenience:
- If `changeOrigin` is not specified, it is set to `true`. This is the most
commonly useful value.
- If `pathRewrite` is not specified, it is set to a single rewrite that removes
the entire prefix and route. In the above example, a rewrite of
`'^/proxy/larger-example/v1/': '/'` is added. That means that a request to
`/proxy/larger-example/v1/some/path` will be translated to a request to
`http://larger.example.com:8080/svc.v1/some/path`.