bui-themer: update README

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2025-09-13 19:05:24 +02:00
parent 6dfa9e796c
commit 2505f616fc
1 changed files with 57 additions and 7 deletions
@@ -1,13 +1,63 @@
 # bui-themer

-Welcome to the bui-themer plugin!
+## Description

-_This plugin was created through the Backstage CLI_
+The Backstage UI Themer helps you convert an existing MUI v5 theme into Backstage UI (BUI) CSS custom properties. It detects installed app themes, generates a complete set of BUI CSS variables for each theme (light and dark), and lets you preview how common BUI components look with your colors and typography. You can copy the generated CSS to the clipboard or download it as a `.css` file, and it works with both the old and new Backstage frontend systems without requiring any backend setup.

-## Getting started
+## Installation

-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/bui-themer](http://localhost:3000/bui-themer).
+### 1) Add the dependency to your app

-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
+Run this from your Backstage repo root:
+
+```bash
+yarn add --cwd packages/app @backstage/plugin-bui-themer
+```
+
+### 2) Wire it up depending on your frontend system
+
+#### Old frontend system (legacy `App.tsx` with `<FlatRoutes>`)
+
+Add a route for the page in your app:
+
+```tsx
+// packages/app/src/App.tsx
+import React from 'react';
+import { Route } from 'react-router-dom';
+import { FlatRoutes } from '@backstage/core-app-api';
+import { BuiThemerPage } from '@backstage/plugin-bui-themer';
+
+export const App = () => (
+  <FlatRoutes>
+    {/* ...your other routes */}
+    <Route path="/bui-themer" element={<BuiThemerPage />} />
+  </FlatRoutes>
+);
+```
+
+#### New frontend system
+
+If package discovery is enabled in your app, this plugin is picked up automatically after installation — no code changes required. Just navigate to `/bui-themer`.
+
+If you prefer explicit registration (or don't use discovery), register the plugin as a feature. The page route (`/bui-themer`) is provided by the plugin.
+
+```tsx
+// packages/app/src/App.tsx (or your app entry where you call createApp)
+import React from 'react';
+import { createApp } from '@backstage/frontend-defaults';
+import buiThemerPlugin from '@backstage/plugin-bui-themer';
+
+const app = createApp({
+  features: [
+    // ...other features
+    buiThemerPlugin,
+  ],
+});
+
+export default app.createRoot();
+```
+
+## Accessing the Themer page
+
+- Navigate to `/bui-themer` in your Backstage app (for example `http://localhost:3000/bui-themer`).
+- Optional: Add a sidebar/link in your app that points to `/bui-themer` if you want a permanent navigation entry.