Document createDevApp pattern for frontend plugin development
Add documentation for the new `@backstage/frontend-dev-utils` package across three docs pages: the frontend system building plugins guide, the CLI build system reference, and the project structure overview. Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com> Made-with: Cursor
This commit is contained in:
@@ -144,7 +144,10 @@ are separated out into their own folder, see further down.
|
||||
|
||||
- [`dev-utils/`](https://github.com/backstage/backstage/tree/master/packages/dev-utils) -
|
||||
Helps you setup a plugin for isolated development so that it can be served
|
||||
separately.
|
||||
separately. This is for plugins using the legacy frontend system.
|
||||
|
||||
- [`frontend-dev-utils/`](https://github.com/backstage/backstage/tree/master/packages/frontend-dev-utils) -
|
||||
Utilities for developing frontend plugins using the new frontend system. Provides the `createDevApp` helper for setting up a minimal development app in a plugin's `dev/` entry point.
|
||||
|
||||
- [`e2e-test/`](https://github.com/backstage/backstage/tree/master/packages/e2e-test) -
|
||||
Another CLI that can be run to try out what would happen if you build all the
|
||||
|
||||
@@ -110,6 +110,21 @@ What we've built here is a very common type of plugin. It's a top-level tool tha
|
||||
|
||||
We have also provided external access to our route reference by passing it to the plugin `routes` option. This makes it possible for app integrators to bind an external link from a different plugin to our plugin page. You can read more about how this works in the [External Route References](../architecture/36-routes.md#external-route-references) section.
|
||||
|
||||
## Running a dev server
|
||||
|
||||
Each frontend plugin package has a `dev/` folder that is used as the entry point when you run `yarn start`. This is a convenient way to run your plugin in isolation during development. The `@backstage/frontend-dev-utils` package provides a `createDevApp` helper that sets up a minimal app for this purpose:
|
||||
|
||||
```tsx title="in dev/index.ts"
|
||||
import { createDevApp } from '@backstage/frontend-dev-utils';
|
||||
import myPlugin from '../src';
|
||||
|
||||
createDevApp({ features: [myPlugin] });
|
||||
```
|
||||
|
||||
This will create and render a Backstage app with only your plugin installed. If you need to include additional features that your plugin depends on, pass them along in the `features` array. You can also forward additional options to `createApp` from `@backstage/frontend-defaults` using the `createAppOptions` option.
|
||||
|
||||
The dev setup is started by running `yarn start` in the plugin directory, which uses the `backstage-cli package start` command. It sets up a local development server with hot reloading, just like a full app.
|
||||
|
||||
## Utility APIs
|
||||
|
||||
Another type of extensions that is commonly used are [Utility APIs](../utility-apis/01-index.md). They can encapsulate shared pieces of functionality of your plugin, for example an API client for a backend service. You can optionally export your Utility API for other plugins to use, or allow integrators to replace the implementation of your Utility API with their own. For details on how to define and provide your own Utility API in your plugin, see the section on [creating Utility APIs](../utility-apis/02-creating.md).
|
||||
|
||||
@@ -294,6 +294,20 @@ will be set up that listens to the protocol, host and port set by `app.baseUrl`
|
||||
in the configuration. If needed it is also possible to override the listening
|
||||
options through the `app.listen` configuration.
|
||||
|
||||
For frontend plugin packages using the new frontend system, the recommended way to
|
||||
set up the `dev/index` entry point is to use the `createDevApp` helper from
|
||||
`@backstage/frontend-dev-utils`. It creates and renders a minimal Backstage app
|
||||
with your plugin loaded:
|
||||
|
||||
```tsx title="in dev/index.ts"
|
||||
import { createDevApp } from '@backstage/frontend-dev-utils';
|
||||
import myPlugin from '../src';
|
||||
|
||||
createDevApp({ features: [myPlugin] });
|
||||
```
|
||||
|
||||
For the legacy frontend system, the `@backstage/dev-utils` package provides equivalent helpers.
|
||||
|
||||
The frontend development bundling is currently based on
|
||||
[Webpack](https://webpack.js.org/) and
|
||||
[Webpack Dev Server](https://webpack.js.org/configuration/dev-server/). The
|
||||
|
||||
Reference in New Issue
Block a user