Configuring App with plugins
Audience: Developers
Backstage plugins are primarily written using TypeScript, Node.js and React. Having an understanding of these technologies will be beneficial on your journey to customizing Backstage!
Summary
Backstage plugins customize the app for your needs. There is a plugin directory with plugins for many common infrastructure needs - CI/CD, monitoring, auditing, and more.
Adding existing plugins to your app
The following steps assume that you have created a Backstage app and want to add an existing plugin to it.
We are using the CircleCI plugin in this example, which is designed to show CI/CD pipeline information attached to an entity in the software catalog.
-
Add the plugin's npm package to the repo:
From your Backstage root directoryyarn --cwd packages/app add @circleci/backstage-plugin
Note the plugin is added to the
app
package, rather than the rootpackage.json
. Backstage Apps are set up as monorepos with Yarn workspaces. Since CircleCI is a frontend UI plugin, it goes inapp
rather thanbackend
. -
Add the
EntityCircleCIContent
extension to the entity pages in the app:packages/app/src/components/catalog/EntityPage.tsximport {
EntityCircleCIContent,
isCircleCIAvailable,
} from '@circleci/backstage-plugin';
const cicdContent = (
<EntitySwitch>
{/* ... */}
<EntitySwitch.Case if={isCircleCIAvailable}>
<EntityCircleCIContent />
</EntitySwitch.Case>
;{/* highlight-add-end */}
</EntitySwitch>
);This is just one example, but each Backstage instance may integrate content or cards to suit their needs on different pages, tabs, etc. In addition, while some plugins such as this example are designed to annotate or support specific software catalog entities, others may be intended to be used in a stand-alone fashion and would be added outside the
EntityPage
, such as being added to the main navigation. -
[Optional] Add a proxy config:
Plugins that collect data off of external services may require the use of a proxy service. This plugin accesses the CircleCI REST API, and thus requires a proxy definition.
app-config.yamlproxy:
'/circleci/api':
target: https://circleci.com/api/v1.1
headers:
Circle-Token: ${CIRCLECI_AUTH_TOKEN}
Adding a plugin page to the Sidebar
In a standard Backstage app created with
@backstage/create-app, the sidebar is managed inside
packages/app/src/components/Root/Root.tsx
. The file exports the entire
Sidebar
element of your app, which you can extend with additional entries by
adding new SidebarItem
elements.
For example, if you install the api-docs
plugin, a matching SidebarItem
could be something like this:
// Import icon from Material UI
import ExtensionIcon from '@material-ui/icons/Extension';
// ... inside the AppSidebar component
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />;
You can also use your own SVGs directly as icon components. Just make sure they
are sized according to the Material UI's
SvgIcon default of 24x24px, and set the
extension to .icon.svg
. For example:
import InternalToolIcon from './internal-tool.icon.svg';
On mobile devices the Sidebar
is displayed at the bottom of the screen. For
customizing the experience you can group SidebarItems
in a SidebarGroup
(Example 1) or create a SidebarGroup
with a link (Example 2). All
SidebarGroup
s are displayed in the bottom navigation with an icon.
// Example 1
<SidebarGroup icon={<MenuIcon />} label="Menu">
...
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
...
<SidebarGroup />
// Example 2
<SidebarGroup label="Search" icon={<SearchIcon />} to="/search">
...
<SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
...
<SidebarGroup />
If no SidebarGroup
is provided a default menu will display the Sidebar
content.