Create Backstage Backend Plugin¶
Let's start with creating Backstage Backend Plugin.
I'm going to write how I created my plugin. This is based on the official guide and a Medium blog post (series). So, this is not something I invented and there likely isn't anything new here.
The idea here is that I write down my experience to serve as my long term memory.
The prior art are these two resources:
- Backstage Docs - Create a Backend plugin
- John Tucker (Medium) - Backstage Plugins by Example - Part 2
Steps¶
The steps we'll take, are the following:
- Initialize a new backend plugin with Yarn
- Embed the plugin in our Backstage copy
- Verify the plugin works within Backstage
- Build and publish it as a standalone NPMJS package
Init Backend Plugin¶
To get started, get to your Backstage code copy. Make sure you're at the root of the code base.
Example
The root directly should be like this:
.
├── README.md
├── app-config.local.yaml
├── app-config.production.yaml
├── app-config.yaml
├── backstage.json
├── catalog-info.yaml
├── dist-types
├── environment.sh
├── examples
├── lerna.json
├── node_modules
├── package.json
├── packages
├── playwright.config.ts
├── plugins
├── tsconfig.json
└── yarn.lock
Name of plugin
The creation command adds -backend automatically.
To create the plugin, we run the yarn new command:
This generates your plugin, which is now located in the folder ./plugins/<nameOfPlugin>.
The initial response should be something like this:
Creating backend plugin @internal/plugin-hello-backend
Checking Prerequisites:
availability plugins/hello-backend ✔
creating temp dir ✔
Executing Template:
copying .eslintrc.js ✔
templating README.md.hbs ✔
templating package.json.hbs ✔
copying setupTests.ts ✔
copying index.ts ✔
templating run.ts.hbs ✔
copying router.test.ts ✔
copying router.ts ✔
templating standaloneServer.ts.hbs ✔
Installing:
moving plugins/hello-backend ✔
backend adding dependency ✔
executing yarn install // this will be "working for some time"
executing yarn lint --fix ✔
🎉 Successfully created backend-plugin
I've named my plugin Hello, but feel free to choose a different name:
Enter to your plugin directory:
And then run the self-run command as follows:
A successful launch emits the following:
This will bootup a Node backend server with your plugin. To verify your plugin works, run the following:
The response should be a 200 OK with a bit of JSON:
Verify in Backstage¶
Oke, so the plugin works in and by itself.
That is not very useful, so let's import it into Backstage.
Set Package Namespace
Before we continue, we should update the Package namespace in package.json.
By default, it is "name": "@internal/...",.
When we publish it to NPMJS.org we need to set this to our username or organization.
We use this full name (namespace + package name) to import our plugin to Backstage. So update it now to your username or organization, to avoid problems later.
In my case, the first three lines of package.json now look like this:
To make this next command easier to use, export your NPMJS name(space):
Go back to the root directory of Backstage (should be cd ../../).
And then run this:
We need to make two more code changes before we can run Backstage and see our plugin live.
First, create a plugin file at ./packages/backend/src/pugins/<name_of_plugin>.ts:
hello.ts
import { createRouter } from '@kearos/plugin-hello-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
logger: env.logger,
});
}
Start the Backstage backend:
And then call our plugin API again:
Warning
Notice the addition of /api there.
Which should return the same response:
This is it for our Backend plugin code.
While we could implement some logic and create an additional end point, for the purpose of having a backend and client plugin working together, this is enough.
Build and Publish to NPMSJS¶
Before we can wrap it up entirely, we need to publish our backend plugin.
To do so, we need to compile the TypeScript and build a NPM package we can publish.
Build Package¶
To compile the type script, we go to the root of the Backstage project, and run the following:
If there are any errors, which there shouldn't, resolve them before continuing.
We can then build the package. First, go back to the plugin folder:
Then run the build:
Once this is done, your plugin should be build and contain a dist folder:
Which gives this result:
.
├── README.md
├── dist
│ ├── index.cjs.js
│ ├── index.cjs.js.map
│ └── index.d.ts
├── node_modules
├── package.json
└── src
├── index.ts
├── run.ts
├── service
│ ├── router.test.ts
│ ├── router.ts
│ └── standaloneServer.ts
└── setupTests.ts
Publish Package¶
Ensure you have an NPMJS.org account and your NPM CLI is logged in:
Then, from the root of your plugin, run the NPM Publish command:
Which should ask you to login to your NPM account:
npm notice
npm notice 📦 @kearos/plugin-hello-backend@0.2.1
npm notice === Tarball Contents ===
npm notice 638B README.md
npm notice 888B dist/index.cjs.js
npm notice 1.2kB dist/index.cjs.js.map
npm notice 235B dist/index.d.ts
npm notice 1.1kB package.json
npm notice === Tarball Details ===
npm notice name: @kearos/plugin-hello-backend
npm notice version: 0.2.1
npm notice filename: kearos-plugin-hello-backend-0.2.1.tgz
npm notice package size: 1.8 kB
npm notice unpacked size: 4.1 kB
npm notice shasum: e7f58.............................bbd05e
npm notice integrity: sha512-uhBJRSVioTMTd[...]xJ6Ti9WH+qluA==
npm notice total files: 5
npm notice
npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access
Authenticate your account at:
https://www.npmjs.com/auth/cli/ebdff4ea-a53d-4575-9786-65a8984815de
Press ENTER to open in the browser..
Once you do, it should return with the following:
We've completed our work on the backend plugin.