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

Merge remote-tracking branch 'upstream/master' into docs-openapi-module

Browse Source 
# Conflicts:
#	docs/features/software-catalog/index.md
This commit is contained in:
Iury Lenon Alves
2026-02-13 20:43:58 +00:00
parent 2715433c80 a2295474a2
commit ded468d1c9
92 changed files with 1551 additions and 1258 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/conf/user-interface/index.md
+29 -28
View File
@@ -103,13 +103,13 @@ Backstage UI is using light by default under `:root` but you can target it more
[data-theme-mode='light'] {
/* Light theme specific styles */
  --bui-bg-neutral-0: #f8f8f8;
  --bui-bg-app: #f8f8f8;
--bui-fg-primary: #000;
}
[data-theme-mode='dark'] {
/* Dark theme specific styles */
  --bui-bg-neutral-0: #333333;
  --bui-bg-app: #333333;
--bui-fg-primary: #fff;
}
```
@@ -122,21 +122,22 @@ We recommend starting with a core set of CSS variables to quickly achieve a bran
And if you’d like to go even further, you can target specific component class names for advanced customization.
| Token Name | Description |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `--bui-bg-neutral-0` | This is used to define the background color of your app. It will only be used once. |
| `--bui-bg-neutral-1` | We ar using this color to sit on top of `--bui-bg-neutral-0` mostly for `Card`, `Dialog`, ... |
| `--bui-bg-neutral-2` | This is for content inside elevated components. This colour is less common. |
| `--bui-bg-solid` | This is used for main actions like primary buttons. |
| `--bui-fg-solid` | This is for texts or icons on top of a solid backgrounds. |
| `--bui-fg-primary` | Your primary text or icon colours. |
| `--bui-fg-secondary` | Your secondary text or icon colours. |
| `--bui-fg-danger` | Used for error states and destructive actions. |
| `--bui-fg-warning` | Used for warning states and cautionary information. |
| `--bui-fg-success` | Used for success states and positive feedback. |
| `--bui-fg-info` | Used for informational content and neutral status. |
| `--bui-border` | Main borders around surfaces like `Card`, `Dialog`, ... |
| `--bui-font-regular` | The main font of your app. |
| Token Name | Description |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `--bui-bg-app` | This is used to define the background color of your app. It will only be used once. |
| `--bui-bg-neutral-1` | We are using this color to sit on top of `--bui-bg-app` mostly for `Card`, `Dialog`, ... |
| `--bui-bg-neutral-2` | This is for content inside elevated components. This colour is less common. |
| `--bui-bg-solid` | This is used for main actions like primary buttons. |
| `--bui-fg-solid` | This is for texts or icons on top of a solid backgrounds. |
| `--bui-fg-primary` | Your primary text or icon colours. |
| `--bui-fg-secondary` | Your secondary text or icon colours. |
| `--bui-fg-danger` | Used for error states and destructive actions. |
| `--bui-fg-warning` | Used for warning states and cautionary information. |
| `--bui-fg-success` | Used for success states and positive feedback. |
| `--bui-fg-info` | Used for informational content and neutral status. |
| `--bui-border-1` | Subtle borders for low-contrast separators. |
| `--bui-border-2` | Main borders around surfaces like `Card`, `Dialog`, ... |
| `--bui-font-regular` | The main font of your app. |
<details>
<summary>All available CSS variables</summary>
@@ -150,11 +151,12 @@ And if you’d like to go even further, you can target specific component class
#### Neutral background colors
These colors form a layered neutral scale for your application backgrounds. `--bui-bg-neutral-0` is the base background color. Each subsequent level (1 through 4) represents an elevated layer, with hover, pressed, and disabled variants for interactive states.
These colors form a layered neutral scale for your application backgrounds. `--bui-bg-app` is the base background color. Each subsequent level (1 through 4) represents an elevated layer, with hover, pressed, and disabled variants for interactive states.
| Token Name | Description |
| ----------------------------- | ------------------------------------------------------------ |
| `--bui-bg-neutral-0` | The base background color of your Backstage instance. |
| `--bui-bg-app` | The base background color of your Backstage instance. |
| `--bui-bg-popover` | The background color used for popovers, tooltips, and menus. |
| `--bui-bg-neutral-1` | First elevated layer. Use for cards, dialogs, and panels. |
| `--bui-bg-neutral-1-hover` | Hover state for elements on neutral-1. |
| `--bui-bg-neutral-1-pressed` | Pressed state for elements on neutral-1. |
@@ -213,15 +215,14 @@ Foreground colours are meant to work in pair with a background colours. Typicall
These border colors are mostly meant to be used as borders on top of any components with low contrast to help as a separator with the different background colors.
| Token Name | Description |
| ----------------------- | --------------------------------------------------- |
| `--bui-border` | It should be used on top of `--bui-bg-neutral-1`. |
| `--bui-border-hover` | Used when the component is interactive and hovered. |
| `--bui-border-pressed` | Used when the component is interactive and hovered. |
| `--bui-border-disabled` | Used when the component is disabled. |
| `--bui-border-danger` | It should be used on top of `--bui-bg-danger`. |
| `--bui-border-warning` | It should be used on top of `--bui-bg-warning`. |
| `--bui-border-success` | It should be used on top of `--bui-bg-success`. |
| Token Name | Description |
| ---------------------- | ------------------------------------------------- |
| `--bui-border-1` | Subtle border for low-contrast separators. |
| `--bui-border-2` | It should be used on top of `--bui-bg-neutral-1`. |
| `--bui-border-danger` | It should be used on top of `--bui-bg-danger`. |
| `--bui-border-warning` | It should be used on top of `--bui-bg-warning`. |
| `--bui-border-success` | It should be used on top of `--bui-bg-success`. |
| `--bui-border-info` | It should be used on top of `--bui-bg-info`. |
#### Special colors
docs/features/software-catalog/index.md
+6
View File
@@ -144,6 +144,12 @@ To fix this, you should install the **OpenAPI Catalog Backend Module**. This mod
For installation instructions and usage, see the [catalog-backend-module-openapi README](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-openapi).
## Unprocessed Entities
Sometimes entities fail to process correctly. The **Unprocessed Entities** feature helps Backstage admins find and diagnose these entities to understand the state of the catalog.
To use this feature, check out the documentation for the [catalog-unprocessed-entities plugin](https://github.com/backstage/backstage/tree/master/plugins/catalog-unprocessed-entities) and its [backend module](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-unprocessed).
## Links
- [[Blog post] Backstage Service Catalog released in alpha](https://backstage.io/blog/2020/06/22/backstage-service-catalog-alpha)
docs/frontend-system/building-apps/07-module-federation.md
+19 -25
View File
@@ -74,29 +74,18 @@ import {
createInstance,
ModuleFederation,
} from '@module-federation/enhanced/runtime';
import { buildRuntimeSharedUserOption } from '@backstage/module-federation-common';
import { loadModuleFederationHostShared } from '@backstage/module-federation-common';
export async function initializeModuleFederation(): Promise<ModuleFederation> {
// Build the shared dependencies configuration
const { shared, errors } = await buildRuntimeSharedUserOption();
// Log any errors loading shared dependencies
if (errors.length > 0) {
for (const err of errors) {
console.error(err.message, err.cause);
}
}
// Initialize Module Federation Runtime
return createInstance({
name: 'app-next',
name: 'app',
remotes: [
{
name: 'my_plugin',
entry: 'http://localhost:3001/mf-manifest.json',
},
],
shared,
shared: await loadModuleFederationHostShared(),
});
}
@@ -108,26 +97,31 @@ export async function loadRemote(
}
```
The `loadModuleFederationHostShared` function loads all shared dependencies in parallel and returns them in the format expected by the Module Federation Runtime. By default it will throw if any shared dependency fails to load. You can pass an `onError` callback to handle errors gracefully instead:
```typescript
const shared = await loadModuleFederationHostShared({
onError: error => console.error(error.message, error.cause),
});
```
### Integration with Feature Loaders
Standard Module Federation runtime API integrates very well with frontend feature loaders,
as shown in the example below:
```typescript title="packages/app/src/App.tsx"
```typescript title="packages/app/src/loader.tsx"
import { createInstance } from '@module-federation/enhanced/runtime';
import { buildRuntimeSharedUserOption } from '@backstage/module-federation-common';
import { loadModuleFederationHostShared } from '@backstage/module-federation-common';
import { createFrontendFeatureLoader } from '@backstage/frontend-plugin-api';
const moduleFederationInstance = createInstance({
name: 'app-next',
remotes: [],
});
const moduleFederationLoader = createFrontendFeatureLoader({
export const moduleFederationLoader = createFrontendFeatureLoader({
async loader() {
moduleFederationInstance.registerShared(
(await buildRuntimeSharedUserOption()).shared,
);
const moduleFederationInstance = createInstance({
name: 'app',
remotes: [],
shared: await loadModuleFederationHostShared(),
});
moduleFederationInstance.registerRemotes([
{
name: 'myFirstRemoteWith2ExposedModules',
docs/getting-started/config/database.md
+3 -5
View File
@@ -211,13 +211,13 @@ You can run Postgres in a Docker container, this is great for local development
First we need to pull down the container image, we'll use Postgres 17, check out the [Postgres Version Policy](../../overview/versioning-policy.md#postgresql-releases) to learn which versions are supported.
```shell
docker pull postgres:17.0-trixie
docker pull postgres:17-bookworm
```
Then we just need to start up the container.
```shell
docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD=<secret> postgres:17.0-trixie
docker run -d --name postgres --restart=always -p 5432:5432 -e POSTGRES_PASSWORD=<secret> postgres:17-bookworm
```
This will run Postgres in the background for you, but remember to start it up again when you reboot your system.
@@ -227,11 +227,9 @@ This will run Postgres in the background for you, but remember to start it up ag
Another way to run Postgres is to use Docker Compose, here's what that would look like:
```yaml title="docker-compose.local.yaml"
version: '4'
services:
postgres:
image: postgres:17.0-trixie
image: postgres:17-bookworm
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: <secret>
docs/golden-path/adoption/001-getting-started.md
+72
View File
@@ -0,0 +1,72 @@
---
id: getting-started
sidebar_label: 001 - Getting started
title: Getting started with Backstage
---
The adoption journey is a bit different than the other Golden Paths. The goal of this guide is to prepare you for a successful implementation of Backstage in your organization. A technical understanding of Backstage is not needed for this Golden Path, just a desire to help the technical team that will be owning your Backstage instance.
:::info
I'd highly recommend poking around https://demo.backstage.io/ before continuing with this guide. It's a test instance of Backstage that provides a good foundation for what to expect from the tool as a user.
:::
## What is Backstage?
At a high level, Backstage is a framework for building developer portals. When implemented successfully, it can reduce toil for your developers by centralizing information like docs and ownership, reducing cognitive overhead due to tool fragmentation and simplify setting up new codebases or integrating with existing ones.
A few examples,
> My company tracks everything with spreadsheets. We have a list of all Github repos and who owns them, but it's becoming more and more of an issue to keep up to date. Teams aren't proactively updating it when new projects are created and it quickly falls out of date with reorgs and team charter changes.
Backstage can help! We provide a core plugin called Software Catalog that automates this process. Teams are asked to maintain a file in their repo with this ownership information and it gets automatically ingested into Backstage where you can view all projects in a single location.
> My developers have been complaining recently about having to use a growing number of different websites and tools in their day to day. It's getting hard to keep track of all of the tools and for those that we don't use frequently, we lose X minutes trying to remember how to access them.
Tool fragmentation is a real issue and Backstage can also help here! You can create plugins tailored for your company that talk to these external services. These plugins can be standalone or integrated with the Software Catalog for better context. Imagine all of your [CI/CD workflows visible directly](https://backstage.io/plugins/) on the page for your team's projects.
It's important to note that Backstage shouldn't be fully replacing these tools, we don't want to reinvent the wheel. The goal is to have all of the really important information in one place. The tool should still be where teams go to do more advanced or in depth work.
> We have been struggling recently with getting teams to use a standard template for new services. There's no standard set of libraries these services are using or standard infra management. It's increasingly difficult as a platform team to manage everything.
Backstage can help here too! The Scaffolder provides a templating framework that you can plug a Golden Path implementation to. Similar to Github template repos, this can provide a standard base for teams to create based off of.
> Our platform teams have been getting more and more support requests to help debug onboarding steps. We've documented these areas really well and there are plenty of examples in Git, but teams keep running into the same issues. It's always either a bad copy paste or they forget to update a template variable. We've started looking into a custom templating solution for this.
Backstage can help! With the Scaffolder, you can create a template that lets users fill in data through a form and uses that data to create a customized template output. This output is usually in the form of PRs to your various source control systems. Imagine you have a repo for traffic configuration, another for infrastructure management and a third for k8s manifests - with the Scaffolder, you can hide all of this complexity. You may still need to get reviews on the output PRs, but no more copy paste issues!
## What does adopting Backstage look like?
a.k.a "what am I signing myself up for?"
Successfully adopting Backstage usually looks something like this,
1. Setting up a PoC.
2. Getting leadership buy-in.
3. Identify a group of key stakeholders for the project and iterate with them aggressively.
4. Launch to the larger organization.
5. Drive Catalog adoption to 100%.
6. Your Backstage implementation starts to receive plugins from developers outside of your team.
A truly successful Backstage implementation bridges delivering value to customers (developers), demonstrating returns to leadership, and fostering an inner source model. It's a long process but has huge dividends for those that achieve it!
## Getting started
Now that you know what to expect, let's walk through how to get started.
:::note
If you're non-technical, it is highly recommended to find a technical partner for help setting up a proof-of-concept for feedback.
:::
### Software Catalog
Let's go to https://demo.backstage.io/ together. When you first navigate to the page, you will be brought to the Software Catalog page. This is a view of all projects currently registered with the (Demo) Backstage instance. There are a series of filters that you can play around with. If you're _really_ interested, we recommend reading through [the software catalog system model](../../features/software-catalog/system-model.md).
Let's click into a Component, say "artist-lookup". This will bring you to a specialized view for that Component. Across the top, you can see tabs for "CI/CD", "API", "Dependencies", "Docs" and "TODOs". For your company, you can change this as you see fit. The important takeaway is that all of these tabs are automatically filtered for this Component which makes it easy to see how this could start to replace many navigation to other tools.
### Scaffolder
Let's go to https://demo.backstage.io/create now. This is the Scaffolder, a place to store reusable templates. Click the "Choose" button in the "Demo template". This will bring you to a form with some information to input. You don't need to fill this out. The main takeaway here is that this form is generated from YAML and doesn't require a frontend team to implement a custom form for each template you want to create.
docs/golden-path/adoption/002-leadership-buy-in.md
+30
View File
@@ -0,0 +1,30 @@
---
id: leadership-buy-in
sidebar_label: 002 - Leadership buy-in
title: Getting leadership buy-in
---
## Summary
In this section, we'll be going over what leadership needs to hear to buy in to your pitch for a developer portal. We expect that you have a good idea of the problem that you want Backstage to solve at your company. If not, we recommend you start small. Look for something that is consistently frustrating developers you work with (this can include you). User interviews are a great way to better understand what needs to improve. It may be IT blocking the creation of new Github repos or databases. It might be 5 hours per week of manual toil that your whole organization has to do. It might be a slow time to production for new services or slow provisioning of test environments. Every company will be different. There is no one size fits all answer we can give you - and if we could, it wouldn't be well-tailored for _your_ leadership team.
## Milestones
Every Backstage adoption journey has well-known milestones.
1. You set up a PoC.
2. You get some users.
3. A group of users _really_ gets the value in the portal and jumps on it. They may even create their own plugins - great!
4. You start to plateau with catalog adoption or daily active users.
5. Leadership starts to get nosy about continued value.
6. You hit a crossroads. Your team either starts to think about building something themselves or going for another off the shelf option or they sit down and do the work to get out of the plateau.
7. If your organization made it this far, you likely now have blocking checks for catalog entries and Backstage is a weekly if not daily portal for your developers - congrats!
Step 4 and 5 are painful moments. Successful Backstage adoptions can lose steam quickly. That's the nature of these things, the excitement will eventually run out and people will go back to their day jobs. Another YAML file or cataloging tool is just overhead and extra toil, regardless of the problem you're solving. Getting leadership on the same page about the value of Backstage is the first step to a very successful adoption story.
### Recommendations
1. Bring something real to your leadership team. This can either be a true proof of concept or [the demo site](https://demo.backstage.io).
2. Define metrics around what you're looking to drive up/down. That may be time to onboarding a new engineer, time to production for a new service, time to mitigate incidents, etc. As we say above, this is the meaty problem that is unique to your company that solving will really move the needle.
3. Lower the barrier to adoption. Many people see yet another YAML file as overhead. If you have an existing cataloging solution, use that to simplify the onboarding process. If you don't, this might be a good opportunity to do that work.
4. Knowledge silos. Every team has preferences on how to do things. Centralizing that data into a single interface while letting teams continue to do things how they want to is a powerful goal and something that Backstage can make happen.
docs/golden-path/adoption/003-setting-up-a-poc.md
+13
View File
@@ -0,0 +1,13 @@
---
id: setting-up-a-poc
sidebar_label: 003 - Setting up a PoC
title: Setting up a PoC
---
If you're non-technical, this section should be completed by your technical partner.
Follow [our golden path for creating an app](../create-app/index.md). Once you have that set up, we recommend adding a few `catalog-info.yaml` files to a few repos/projects you own and setting up [the GitHub catalog provider](../../integrations/github/discovery.md).
At this stage, you likely want to just get the instance running on your local machine. We'll go over preparing your instance for production at the end of chapter 2.
You may be tempted to update the theme or add that one plugin your organization _needs_, but hold strong. We'll get there in chapter 3.
docs/golden-path/adoption/004-first-stakeholder-feedback.md
+17
View File
@@ -0,0 +1,17 @@
---
id: first-stakeholder-feedback
sidebar_label: 004 - Stakeholder Feedback
title: First round of stakeholder feedback
---
Now that you have a PoC running, let's walk through how to get good feedback. You likely aren't the first person to hear about Backstage or maybe not even the first person to set up a PoC. There may be common pitfalls unique to your company that are worth knowing about - political, organizational or otherwise.
## Who to look for?
This depends pretty significantly on your organizational structure. If you have a dedicated platform organization or platform team, start with them. They will either be the technical owners of this application from the go, or will eventually take over ownership. Be kind to them. If you aren't from that organization, we recommend finding your technical partner from somewhere in that organization.
## What to listen for
1. IT slowness. Does your organization run on tickets? Are there specific tasks that feel like they should be automated but aren't?
2. User toil. Your developers are super aware of what's slowing them down, they'll tell you the annoying manual parts of their job that they're hoping you can fix.
3. Data sprawl. What services are your users struggling to remember? What vendors are critical but most users only touch once a month?
docs/golden-path/adoption/005-customizing-your-instance.md
+15
View File
@@ -0,0 +1,15 @@
---
id: customize-your-instance
sidebar_label: 005 - Customizing your instance
title: Customizing your instance
---
You now have the knowledge of what your users want and the go from leadership to continue investing in Backstage. Your job now is to customize your instance for your users to really get the value from. Let's dive in!
## Open Source or Build it yourself?
There's a huge community of plugins available for easy installation at https://backstage.io/plugins. We would recommend that you start here for any needs you may be trying to solve. Building a plugin yourself requires significant effort and can be hard to justify early on in your adoption story. If there is a clear gap in the existing offerings for your company, you should build something yourself - otherwise, save yourself the maintenance overhead.
## Customizing the theme
Many organizations are tempted to spend a long time making sure the portal resembles their other offerings. This is important but shouldn't be a months long ordeal. Get it looking close enough and iterate.
docs/golden-path/adoption/006-preparing-for-ga.md
+19
View File
@@ -0,0 +1,19 @@
---
id: preparing-for-ga
sidebar_label: 006 - Preparing for GA
title: Preparing for GA
---
We hope at this point that the developers you're working with have read the [golden path on deploying Backstage](../deployment/index.md). Your Backstage instance should be ready for the scale that comes with a full company launch.
## Launch Announcements
<!--TODO-->
## What to expect in the coming months
<!--TODO-->
## How to keep iterating
<!--TODO-->
docs/golden-path/adoption/007-plugin-ownership.md
+17
View File
@@ -0,0 +1,17 @@
---
id: plugin-ownership
sidebar_label: 007 - Plugin Ownership
title: Plugin Ownership
---
You're now well on your way to a healthy Backstage instance! It's been launched to the whole company and you're loving the feedback developers are giving you. Some developers have even started broaching writing their own plugins.
## Inner source
Accepting internal contributions from other teams is a good sign that you are on the road to a developer portal tailored for your developers. This is a well paved path with many upsides, but a few downsides as well. As your Backstage instance grows in size and age, those same developers may be difficult to find. Your team may start to experience more and more struggle updating Backstage.
<!--TODO-->
## Registering Plugins in Your Catalog
<!--TODO-->
docs/golden-path/adoption/008-full-catalog.md
+15
View File
@@ -0,0 +1,15 @@
---
id: full-catalog
sidebar_label: 008 - A Full Catalog
title: Ensuring your catalog stays complete
---
Along your Backstage journey (and any workflow migration journey), you will hit a point where incremental adoption is no longer easy. The new developers are no longer flowing into your tool like they once did. More and more projects are not being listed in your catalog. Something has to change.
## Enforcing Catalog Files in CI
<!--TODO-->
## Leadership Initiatives
<!--TODO-->
docs/golden-path/adoption/meta.md → docs/golden-path/adoption/__meta__.md
+3 -3
View File
@@ -19,6 +19,8 @@ Users should already have read through the summary section of the docs, "What is
We recommend you poke around the demo site to get a feel for what Backstage can provide. If you're technical, or working with someone technical, you can run through the steps in `golden-path/create-app` and `golden-path/deploying-backstage` to get something running for just your company.
## Getting leadership buy-in
## First round of stakeholder feedback
If you think Backstage is a good fit for your company, it's likely there are others that do or will think the same. You may have already identified them. For this initial round of feedback, share recommendations for what that group should look like, is there any required number of technical or non-technical members, do you need leadership involved at this point, etc.
@@ -29,9 +31,7 @@ For non-technical users, it's recommended to find a technical partner to help st
At this point, we're assuming you already have an instance created through `golden-path/create-app` and `golden-path/deploying-backstage`. You should now start customizing it to your company's needs. We recommend you start small, write some catalog-info YAML files and start to build a personalized catalog.
## Second round of stakeholder feedback
## Getting leadership buy-in
## Preparing for GA
## Plugin ownership and inner source mentality
docs/golden-path/deployment/meta.md → docs/golden-path/deployment/__meta__.md
View File
docs/golden-path/deployment/index.md
View File
docs/golden-path/plugins/__meta__.md
+15
View File
@@ -0,0 +1,15 @@
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
## Why build plugins?
This section should clearly explain why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality.
## Sustainable plugin development
Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create
- a new vendor integration like PagerDuty,
- a new plugin backend that talks to an internal service,
- etc.
This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success.
docs/golden-path/plugins/backend/001-first-steps.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
id: 001-first-steps
id: first-steps
sidebar_label: 001 - Scaffolding the plugin
title: How to scaffold a new plugin?
---
docs/golden-path/plugins/backend/002-poking-around.md
+38 -3
View File
@@ -1,5 +1,5 @@
---
id: 002-poking-around
id: poking-around
sidebar_label: 002 - Poking around
title: 002 - Poking around
---
@@ -16,7 +16,7 @@ To make this plugin production ready, we'll need to adjust a few things,
## Testing locally
Before we jump in to making this plugin ready to ship, let's walk through how to run it locally. If you open your backend plugin's manifest (`plugins/todo-backend/package.json`), and look at the `scripts` section, you'll notice a few important commands. The ones relevant to use right now are
Before we jump in to making this plugin ready to ship, let's walk through how to run it locally. If you open your backend plugin's manifest (`plugins/todo-backend/package.json`), and look at the `scripts` section, you'll notice a few important commands. The ones relevant to us right now are
1. `yarn start` - Starts a local development server using the content in `dev/index.ts` as the backend.
2. `yarn test` - Runs all of the tests for your backend plugin.
@@ -27,8 +27,43 @@ If you run `yarn start`, you should see a custom backend for just your plugin st
2025-06-08T16:14:53.229Z rootHttpRouter info Listening on :7007
```
This indicates that your HTTP server is up and running and we can start sending test HTTP requests. Grab your favorite HTTP client and let's get testing! If you aren't sure what to use, I'd recommend the `humao.rest-client` VSCode extension which can easily be run in VSCode itself with very little extra set up.
This indicates that your HTTP server is up and running and we can start sending test HTTP requests. Grab your favorite HTTP client and let's get testing!
To start, let's make sure we're starting from a clean slate. You can list all existing TODOs by running the command below. You should get back an empty list:
```sh
curl http://localhost:7007/api/todo/todos
```
To create a new TODO, you can send a POST request to the same endpoint. However, you will get a 401 error right now.
```sh
curl -X POST http://localhost:7007/api/todo/todos \
-H 'Content-Type: application/json; charset=utf-8' \
--data-binary @- << EOF
{
"title": "My Todo"
}
EOF
```
The 401 error is because we track the ID of the user that created each TODO. If you send a request to create a TODO but don't provide an `Authorization` header, you will see this failure. For plugins that have a frontend as well, this credential management should happen automatically. Let's try this:
```sh
curl -v -X POST http://localhost:7007/api/todo/todos \
-H 'Content-Type: application/json; charset=utf-8' \
-H "Authorization: Bearer $(curl -s http://localhost:7007/api/auth/guest/refresh | jq -r '.backstageIdentity.token')" \
--data-binary @- << EOF
{
"title": "My Todo"
}
EOF
```
We can then list all TODOs to see our new TODO!
```sh
curl http://localhost:7007/api/todo/todos
```
You'll notice that `createdBy` is `user:development/guest` which is the token we used to create the TODO. That's the `-H "Authorization: Bearer $(curl -s http://localhost:7007/api/auth/guest/refresh | jq -r '.backstageIdentity.token')"` part of the request.
docs/golden-path/plugins/backend/003-persistence.md
+19
View File
@@ -0,0 +1,19 @@
---
id: persistence
sidebar_label: 003 - Persisting your TODOs
title: 003 - Persisting your TODOs
---
## Saving Plugin State Indefinitely
You may have noticed that your list of TODOs disappears after you restart your Backstage backend. The general flow to restart your backend without having to rerun `yarn start` is to press ENTER on the terminal running `yarn start`. This will force the Backstage backend to restart completely, wiping out any in memory data and starting everything from scratch -- everything except your database.
### Quick intro to SQLite
SQLite is the default database for local development. It runs in memory (and can also run from a file on disk). It supports quick iteration cycles and can be easily deleted if anything goes wrong.
## Adding the `databaseService` to your plugin
<!--TODO-->
## Testing your changes
docs/golden-path/plugins/backend/004-source-tracked.md
+19
View File
@@ -0,0 +1,19 @@
---
id: source-tracked
sidebar_label: 004 - Integrating with SCMs
title: 004 - Git-tracked TODOs
---
Problem: You have TODOs in your source code that you want to ingest with your plugin.
## Authenticating
<!--TODO-->
## Querying
<!--TODO-->
## Fetching
<!--TODO-->
docs/golden-path/plugins/backend/005-testing.md
+29
View File
@@ -0,0 +1,29 @@
---
id: testing
sidebar_label: 005 - Unit testing your plugin
title: 005 - Testing
---
## Testing is important
We've done a lot of manual testing up to this point of functionality. Let's start putting those assumptions into code that we can run on every change to ensure things are working correctly.
## Router-level testing
<!--TODO-->
## Plugin-level testing
<!--TODO-->
## OpenAPI testing
<!--TODO-->
### Integration with Jest tests
<!--TODO-->
### Fuzzing
<!--TODO-->
docs/golden-path/plugins/backend/__meta__.md
+4 -35
View File
@@ -1,36 +1,7 @@
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
# Glossary
- Page: A single `md` file.
- Guide: A number of pages grouped under the same folder.
# Overall Writing Guidelines
The goal of these docs is to provide a comprehensive set of guides that developers + admins can use to quickly get up to speed with plugin development, and then refer to as they're developing their own plugins.
A user that finishes all of these guides will feel comfortable implementing plugins on their own. If additional assistance is required, they should be referred to other sources of information such as Discord, GitHub, source code, or documentation for further support. The user will also understand why/when to build their own plugins, inner-sourcing their developer portal and contributing internal plugins back to the open-source project.
At the same time, not all users will finish the docs or they may come back to them as required. Individual guides should have strong "abstracts" (what will I learn by reading this guide), table of contents, and "next steps" (what do I need to do next) to guide users to read the most important pieces for their work.
When writing guide pages, keep it light! These should be instructional docs, and at the same time conversational and a joy to read. Guides should build on each other, when reading through a progression, the reader should feel more comfortable and confident with concepts as they pop up across progression levels. Guides should be standalone, when finishing one level (for example 101), you should be able to immediately jump into the next (201) without additional research or background. Referencing previous progression levels is ok.
# Sections
## Why build plugins?
This section should answer definitely why you should build a new plugin. The Backstage framework is deeply empowered by plugins and plugins are core to the project's success. Users should walk away from reading this section with a conviction that plugins are the right path for new functionality.
## Sustainable plugin development
Plugins are not developed in a vacuum. Users should reach for them to solve specific business problems facing their developers, for example, you may be tasked to create
- a new vendor integration like PagerDuty,
- a new plugin backend that talks to an internal service,
- etc.
This section should contain learnings from successful Backstage deployments about how to engage with stakeholders, how/when to iterate on your plugin, and setting yourself up for future success.
## Creating your first plugin
This section should be extremely deliberate in showing readers every step of the way to create a plugin using Backstage's best practices. A reader that finishes this section should feel extremely comfortable creating new plugins and how to install and use plugins regardless of their experience with JS/TS and Backstage.
@@ -78,12 +49,6 @@ app.get('/list', async (req, res) => {
});
```
### Testing
Let's write a unit test using `supertest` to make sure that everything is working as expected.
After verifying everything, introduce the problem of persistence - the todos aren't saved across reloads.
### Persistence
Saving values to the database. Writing a migrations file. Plumbing through the database service.
@@ -91,3 +56,7 @@ Saving values to the database. Writing a migrations file. Plumbing through the d
## SCM Integrations
Our users love the new plugin, and now they want it to automatically fetch todos from their source code.
### Testing
Let's write a unit test using `supertest` to make sure that everything is working as expected.
docs/golden-path/plugins/backend/todo.http
-12
View File
@@ -1,12 +0,0 @@
POST http://localhost:7007/api/todo/todos
Content-Type: application/json
{
"title": "My First TODO"
}
###
GET http://localhost:7007/api/todo/todos
###
docs/golden-path/plugins/frontend/001-first-steps.md
+15
View File
@@ -0,0 +1,15 @@
---
id: first-steps
sidebar_label: 001 - Scaffolding the plugin
title: How to scaffold a new plugin?
---
Running `yarn new` -> `frontend-plugin`.
## What did we create?
<!--TODO-->
## Common issues
<!--TODO-->
docs/golden-path/plugins/frontend/002-poking-around.md
+17
View File
@@ -0,0 +1,17 @@
---
id: poking-around
sidebar_label: 002 - Poking around
title: 002 - Poking around
---
Our frontend TODO plugin is a bit more simplistic than the backend one. We need to implement a new UI to replace the example components we have.
Let's use this React component to start. Copy this to `plugins/todo/src/components/TodoList.tsx`.
```tsx
// todo
```
### Data Mocking
You already have a backend with dynamic data. Let's start a little smaller. Using hard coded data can be a great way to iterate quickly.
docs/golden-path/plugins/frontend/003-dynamic-config.md
+29
View File
@@ -0,0 +1,29 @@
---
id: dynamic-config
sidebar_label: 003 - Dynamic Config
title: 003 - Dynamic Config
---
Your plugin should have been generated by default for the New Frontend System which is config-first. That means you can easily control your frontend components through your `app-config.yaml`.
Let's try this quickly by disabling our entire TODO page,
```yaml
# TODO
```
We can also do really cool things like provide React props directly through config. Let's try moving our hard coded list of TODOs to config instead,
```tsx
// todo
```
and the config,
```yaml
# TODO
```
### Why does this work?
<!--TODO-->
docs/golden-path/plugins/frontend/004-http-client.md
+17
View File
@@ -0,0 +1,17 @@
---
id: http-client
sidebar_label: 004 - HTTP Client
title: 004 - HTTP Client
---
Now, let's really make our page dynamic. We'll start by writing an HTTP client by hand.
```tsx
class TodoClient {
// TODO
}
```
## OpenAPI Generated Clients
You can also skip a step and ensure your frontend and backend stay in sync by generating the client from an OpenAPI schema.
docs/golden-path/plugins/frontend/005-testing.md
+15
View File
@@ -0,0 +1,15 @@
---
id: testing
sidebar_label: 005 - Testing
title: 005 - Testing
---
Everyone's favorite part! Let's make sure our components continue to work even when we're not able to validate the changes.
## Unit Tests
Use Jest + RTL + MSW v2.
## Integration Tests
Use Playwright.
docs/golden-path/plugins/frontend/__meta__.md
+34
View File
@@ -0,0 +1,34 @@
<!-- THIS FILE IS NOT INTENDED TO BE DISPLAYED ON THE DOCSITE -->
# Sections
## Creating your first plugin
### Scaffolding a new plugin
Talk through how to run the `backstage-cli create` command as well as what the output it creates is. This should touch on why we install this into `packages/app`.
### Debugging
How to handle common errors.
## First steps with the new plugin
### Creating a todo plugin
We're going to be creating the frontend for a todo list plugin. We want the user to be able to create todos for themselves and show the user their current list of todos.
To start, we'll use a list of mocked data.
### Controlling your component dynamically
Update the mocked data to be controlled by config.
### HTTP API
We want our todo plugin to reach the backend that we implemented in [the backend plugin Golden Path](../backend/001-first-steps.md). Let's write a client to do this (or use OpenAPI to generate a client for us).
### Testing
Unit tests - Let's write a unit test using React Testing Library to make sure that everything is working as expected.
Integration tests - Let's write an integration test using Playwright to _really_ make sure everything is working.
docs/golden-path/plugins/integrations/001-catalog.md
+23
View File
@@ -0,0 +1,23 @@
---
id: catalog
sidebar_label: 001 - Catalog
title: Integrating with Catalog
---
## Software Catalog
### What is the Software Catalog?
<!--TODO-->
### Integration Points
<!--TODO-->
## Adding a new `backstage.io/todo` annotation
<!--TODO-->
## Custom TODO Entity Kind
<!--TODO-->
docs/golden-path/plugins/integrations/002-search.md
+19
View File
@@ -0,0 +1,19 @@
---
id: search
sidebar_label: 002 - Search
title: Integrating with Search
---
## Search
### What is Backstage Search?
<!--TODO-->
### Common integration points
<!--TODO-->
## Creating a custom TODO collator
<!--TODO-->
docs/golden-path/plugins/integrations/003-permissions.md
+23
View File
@@ -0,0 +1,23 @@
---
id: permissions
sidebar_label: 003 - Permissions
title: Integrating with the Permission framework
---
## Permissions
### What is the Permissions framework?
<!--TODO-->
### Common integration points
<!--TODO-->
## Creating private TODOs
<!--TODO-->
## Restricting who can create TODOs
<!--TODO-->
docs/golden-path/plugins/integrations/004-notifications.md
+23
View File
@@ -0,0 +1,23 @@
---
id: notifications
sidebar_label: 004 - Notifications
title: Integrating with Notifications
---
## Notifications
### What are Backstage Notifications?
<!--TODO-->
### Common integration points
<!--TODO-->
## TODO with an alarm
<!--TODO-->
## Create TODOs for other people and notify them
<!--TODO-->
docs/releases/v1.48.0-next.2-changelog.md
+1 -1
View File
@@ -90,7 +90,7 @@ Upgrade Helper: [https://backstage.github.io/upgrade-helper/?to=1.48.0-next.2](h
```diff
- background: var(--bui-bg-surface-0);
+ background: var(--bui-bg-neutral-0);
+ background: var(--bui-bg-app);
```
Replace on-surface tokens shifted by +1: