Lighthouse is a Google tool that audits web pages for performance, accessibility, SEO, and best practices. It gives clear scores so teams can see what to fix and what improved.
The Lighthouse Backstage plugin brings those audits into your portal. You can run checks on demand, view full reports, and watch scores trend over time. This makes it easier to spot regressions after a release and to track improvements across teams. You can link website URLs to catalog entities so results show up right beside the services that own them. It also supports scheduled runs through a backend service if you want regular snapshots.
Typical use cases include keeping an eye on accessibility budgets, monitoring performance across many sites, and catching SEO issues before launch. For engineers, the benefit is simple. You get web quality data where your work lives, next to the catalog, docs, builds, and ownership. If your teams ship websites or docs sites, this plugin helps you see quality trends and act on them without leaving Backstage.
Installation Instructions
These instructions apply to self-hosted Backstage only. To use this plugin on Roadie, visit the docs.
Prepare a Lighthouse Audit Service
- Start an instance of lighthouse audit service that your Backstage app can reach
- Enable CORS on that service by setting the LAS_CORS environment variable to true when you start it
# Example of setting the CORS environment variable before starting the service
export LAS_CORS=true
# start your lighthouse audit service hereInstall the frontend plugin
- Add the plugin to your Backstage app
# from your Backstage root directory
yarn --cwd packages/app add @backstage-community/plugin-lighthouseIf your app uses Feature Discovery
- No code changes are needed in App.tsx
- The plugin page and nav item register automatically
If your app does not use Feature Discovery
- Enable the plugin in packages app src App.tsx
// packages/app/src/App.tsx
import lighthousePlugin from '@backstage-community/plugin-lighthouse';
import { createApp } from '@backstage/core-app-api';
// other imports
export const app = createApp({
features: [
// other features
lighthousePlugin,
],
});
// rest of your fileLegacy frontend routing
- Add the route in packages app src App.tsx
// packages/app/src/App.tsx
import React from 'react';
import { Route } from 'react-router';
import { FlatRoutes } from '@backstage/core-app-api';
import { LighthousePage } from '@backstage-community/plugin-lighthouse';
// other imports
const routes = (
<FlatRoutes>
{/* other routes */}
<Route path="/lighthouse" element={<LighthousePage />} />
</FlatRoutes>
);
// rest of your fileConfigure the service url
- Point the plugin to your lighthouse audit service in app config
- Allow the service in the backend content security policy so the audit reports can load in an iframe
# app-config.yaml
backend:
csp:
frame-src:
- http://your-service-url
lighthouse:
baseUrl: http://your-service-urlReplace the url with your service address
Add Lighthouse to the Catalog entity page
- Annotate a catalog entity with a website url
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: my-service
annotations:
lighthouse.com/website-url: https://backstage.io/
spec:
type: service
lifecycle: production
owner: guests- Add a Lighthouse tab to packages app src components catalog EntityPage.tsx
// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { EntityLighthouseContent } from '@backstage-community/plugin-lighthouse';
// other imports
const websiteEntityPage = (
<EntityLayout>
{/* other tabs */}
<EntityLayout.Route path="/lighthouse" title="Lighthouse">
<EntityLighthouseContent />
</EntityLayout.Route>
</EntityLayout>
);
// export your composed entity pages as usual- Add a Lighthouse card to the overview tab
// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import Grid from '@material-ui/core/Grid';
import { EntitySwitch } from '@backstage/plugin-catalog';
import {
EntityLastLighthouseAuditCard,
isLighthouseAvailable,
} from '@backstage-community/plugin-lighthouse';
// inside your overview content
const overviewContent = (
<Grid container spacing={3} alignItems="stretch">
{/* other content */}
<EntitySwitch>
<EntitySwitch.Case if={isLighthouseAvailable}>
<Grid item md={6}>
<EntityLastLighthouseAuditCard />
</Grid>
</EntitySwitch.Case>
</EntitySwitch>
</Grid>
);Notes on backend usage
- This plugin is a frontend that talks to the lighthouse audit service
- There is no Backstage backend package required for core use
- For automated schedules you can install the separate lighthouse backend plugin if you need it
Things to Know
Backend
This plugin is only a frontend layer for lighthouse-audit-service and won’t work without it.
Changelog
This changelog is produced from commits made to the Lighthouse plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.
Breaking changes
- Remove support for the legacy backend in the Lighthouse backend package #2584 merged 8 months ago. Migrate to the new backend system. Remove imports from @backstage/backend-common.
Features
- Remove the scheduler filter that required spec type website #3451 merged 6 months ago. Audits now run for any component that has the Lighthouse website url annotation.
Deprecations
- Deprecate the legacy backend for Lighthouse #2051 merged 10 months ago.
Maintenance
Set up Backstage in minutes with Roadie
Focus on using Backstage, rather than building and maintaining it.