Creating Your Own Plugin

In this guide you’ll build a small frontend plugin for Backstage that fetches a random piece of advice from the Advice API (https://api.adviceslip.com/advice) and renders it as a compact card on an entity page. This practical example demonstrates:

How to scaffold a frontend plugin in a Backstage repository
How Backstage plugins declare routes and expose extensions
How to implement a React component that fetches data using Backstage APIs
How to register a component extension so it can be embedded in the app

Prerequisites: a working Backstage repository and basic familiarity with React.

Make sure your development environment can run the Backstage frontend (Node.js, Yarn) and that you understand basic React hooks (useState, useEffect). This example focuses on frontend plugin development and using Backstage APIs like useApi and fetchApiRef.

1) Scaffolding a frontend plugin

Backstage includes a generator to add new packages to a monorepo. From the project root run:

yarn new

When prompted:

? What do you want to create? plugin - A new frontend plugin
? Enter the ID of the plugin [required] advice

Choose “plugin - A new frontend plugin” and enter an ID such as advice. The generator will create the plugin under plugins/advice and update the root frontend package dependencies (for example, adding "@internal/backstage-plugin-advice": "^0.1.0" to the root package.json). Expected output includes messages like:

Creating frontend plugin @internal/backstage-plugin-advice
...
Successfully created plugin

2) What the generator creates (important files)

Open plugins/advice/src. The generator provides several files you will use:

File	Purpose	Notes / Example
`routes.ts`	Defines route references used for navigation	See example below
`plugin.ts`	Registers the plugin and exposes page/extension entry points	Exposes routable and component extensions
`components/ExampleComponent.tsx`	Example full-page React component	Useful as a reference for page routing
`index.ts`	Re-exports the plugin’s public exports	e.g. `export { advicePlugin, AdvicePage } from './plugin';`

routes.ts

// plugins/advice/src/routes.ts
import { createRouteRef } from '@backstage/core-plugin-api';

export const rootRouteRef = createRouteRef({
  id: 'advice',
});

plugin.ts (routable page example)

// plugins/advice/src/plugin.ts
import {
  createPlugin,
  createRoutableExtension,
} from '@backstage/core-plugin-api';

import { rootRouteRef } from './routes';

export const advicePlugin = createPlugin({
  id: 'advice',
  routes: {
    root: rootRouteRef,
  },
});

export const AdvicePage = advicePlugin.provide(
  createRoutableExtension({
    name: 'AdvicePage',
    component: () =>
      import('./components/ExampleComponent').then(m => m.ExampleComponent),
    mountPoint: rootRouteRef,
  }),
);

The generator also adds tests and a basic Storybook setup for the plugin.

3) Creating a reusable component extension (AdviceCard)

For this lesson we want a small, embeddable component — an AdviceCard — that can be placed on an entity overview page. To make it reusable across the app we will export it as a component extension. Create the component file:

// plugins/advice/src/components/AdviceCard.tsx
import React, { useEffect, useState } from 'react';
import { InfoCard } from '@backstage/core-components';
import { fetchApiRef, useApi } from '@backstage/core-plugin-api';

export const AdviceCard = () => {
  const fetchApi = useApi(fetchApiRef);
  const [advice, setAdvice] = useState<string | null>(null);

  useEffect(() => {
    let mounted = true;

    fetchApi
      .fetch('https://api.adviceslip.com/advice')
      .then(res => res.json())
      .then(data => {
        if (!mounted) return;
        // data shape: { slip: { id: number, advice: string } }
        setAdvice(data?.slip?.advice ?? 'No advice available');
      })
      .catch(() => {
        if (!mounted) return;
        setAdvice('Could not fetch advice');
      });

    return () => {
      mounted = false;
    };
  }, [fetchApi]);

  return <InfoCard title="Advice of the Day">{advice}</InfoCard>;
};

Add a small index file that re-exports the component:

// plugins/advice/src/components/index.ts
export { AdviceCard } from './AdviceCard';

Now expose the component from plugin.ts using createComponentExtension (so other parts of the app can import and render it):

// plugins/advice/src/plugin.ts
import {
  createPlugin,
  createComponentExtension,
  createRoutableExtension,
} from '@backstage/core-plugin-api';

import { rootRouteRef } from './routes';

export const advicePlugin = createPlugin({
  id: 'advice',
  routes: {
    root: rootRouteRef,
  },
});

export const AdvicePage = advicePlugin.provide(
  createRoutableExtension({
    name: 'AdvicePage',
    component: () =>
      import('./components/ExampleComponent').then(m => m.ExampleComponent),
    mountPoint: rootRouteRef,
  }),
);

export const AdviceCardExtension = advicePlugin.provide(
  createComponentExtension({
    component: {
      lazy: () => import('./components/AdviceCard').then(m => m.AdviceCard),
    },
  }),
);

Finally, export the plugin and its extensions from src/index.ts:

// plugins/advice/src/index.ts
export { advicePlugin, AdvicePage, AdviceCardExtension } from './plugin';

Note: The export name you choose (for example AdviceCardExtension) is the identifier other packages will import.

4) Using the plugin in the app

The generator wires the routable AdvicePage into the app router. In packages/app/src/App.tsx you might see:

import { AdvicePage } from '@internal/backstage-plugin-advice';

and a router entry such as:

{/* inside the app routing */}
<Route path="/advice" element={<AdvicePage />} />

To embed the Advice card on an entity overview, import the provided component extension into the file that composes the entity “Overview”. For example:

// packages/app/src/components/catalog/EntityPage.tsx (excerpt)
import { AdviceCardExtension } from '@internal/backstage-plugin-advice';

// ... inside the Overview grid JSX
<Grid container spacing={3} direction="column">
  <Grid item md={3}>
    <AdviceCardExtension />
  </Grid>
  {/* other Grid items */}
</Grid>

Important: when referencing JSX tags in MDX text, wrap them in backticks to avoid MDX parsing (for example AdviceCardExtension).

5) Styling with Backstage UI components

Backstage uses Material-UI and provides curated UI primitives in @backstage/core-components. Use these building blocks for a consistent look-and-feel rather than custom CSS. Common components:

Component	Use case
`InfoCard`	Compact card for summaries and small widgets (used for AdviceCard)
`Page`, `Header`, `Content`	Page layout and top-level structure
`Grid`	Responsive layout for arranging cards and widgets

We used InfoCard in the AdviceCard to inherit Backstage styling and accessibility defaults.

A screenshot of a documentation webpage (Material UI) showing the "Card" component with examples and explanatory text. The page includes a left navigation menu of UI components and a right-side contents list.

Backstage also publishes a Storybook with component examples — a helpful resource to discover available components and copy working snippets.

A Storybook UI screenshot showing an "Information Card" component preview with a subheader and lorem ipsum body text. The left sidebar lists components and the lower panel shows controls for the card's props.

6) Why use Backstage APIs for fetch (`useApi` + `fetchApiRef`)

Prefer Backstage’s injectable fetch API over the global fetch. Benefits:

Centralized configuration (proxying, auth headers, base URLs)
Consistent logging and error handling across plugins
Easier testability and mocking in unit tests

We used them like this in AdviceCard:

import { fetchApiRef, useApi } from '@backstage/core-plugin-api';

const fetchApi = useApi(fetchApiRef);
fetchApi.fetch('https://api.adviceslip.com/advice')

This integrates your requests with the app’s HTTP pipeline and makes it simpler to add auth, retries, or proxy rules later.

7) Running and developing the plugin independently

Develop plugins without booting the entire Backstage app. Common ways:

From the plugin folder:

cd plugins/advice
yarn start

From the repo root using Yarn workspaces:

yarn workspace @internal/backstage-plugin-advice start

Either command runs a local dev server for the plugin so you can iterate quickly. The server prints the URL, e.g. http://localhost:3000/, where you can preview the plugin UI.

A web app dashboard screenshot with a purple header reading "Welcome to advice!" and a page titled "My Plugin Title" showing an information card and an "Example User List" table of avatars, names, emails, and nationalities. A dark left navigation panel with items like "Root Page," "Switch Theme," and "Sign Out" is also visible.

8) Recap — complete AdviceCard component

For convenience, here is the final AdviceCard.tsx:

// plugins/advice/src/components/AdviceCard.tsx
import React, { useEffect, useState } from 'react';
import { InfoCard } from '@backstage/core-components';
import { fetchApiRef, useApi } from '@backstage/core-plugin-api';

export const AdviceCard = () => {
  const fetchApi = useApi(fetchApiRef);
  const [advice, setAdvice] = useState<string | null>(null);

  useEffect(() => {
    let mounted = true;

    fetchApi
      .fetch('https://api.adviceslip.com/advice')
      .then(res => res.json())
      .then(data => {
        if (!mounted) return;
        setAdvice(data?.slip?.advice ?? 'No advice available');
      })
      .catch(() => {
        if (!mounted) return;
        setAdvice('Could not fetch advice');
      });

    return () => {
      mounted = false;
    };
  }, [fetchApi]);

  return <InfoCard title="Advice of the Day">{advice}</InfoCard>;
};

That covers creating a simple, reusable frontend plugin in Backstage: scaffolding, registering a component extension, using Backstage UI primitives, and performing API requests through the Backstage fetch API. From here you can extend the plugin with caching, explicit loading/error states, tests, configuration via the Backstage config system, or a backend proxy if you need to avoid CORS or rate limits. Links and references

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Creating Your Own Plugin

1) Scaffolding a frontend plugin

2) What the generator creates (important files)

3) Creating a reusable component extension (AdviceCard)

4) Using the plugin in the app

5) Styling with Backstage UI components

6) Why use Backstage APIs for fetch (`useApi` + `fetchApiRef`)

7) Running and developing the plugin independently

8) Recap — complete AdviceCard component

Watch Video

​1) Scaffolding a frontend plugin

​2) What the generator creates (important files)

​3) Creating a reusable component extension (AdviceCard)

​4) Using the plugin in the app

​5) Styling with Backstage UI components

​6) Why use Backstage APIs for fetch (useApi + fetchApiRef)

​7) Running and developing the plugin independently

​8) Recap — complete AdviceCard component

Watch Video

1) Scaffolding a frontend plugin

2) What the generator creates (important files)

3) Creating a reusable component extension (AdviceCard)

4) Using the plugin in the app

5) Styling with Backstage UI components

6) Why use Backstage APIs for fetch (`useApi` + `fetchApiRef`)

7) Running and developing the plugin independently

8) Recap — complete AdviceCard component