import { CodeBlock } from '@/components/CodeBlock';
import { Banner } from '@/components/Banner';
import {
  snippet,
  analyticsSetupSnippet,
  analyticsNoTrackSnippet,
} from './snippets';

# Installation

## Import BUI's global styles

Backstage UI works by importing a global CSS file at the root of your application. This file includes all the default styles for the components.
First, you'll need to install the package using a package manager. For example, if you're using Yarn:

<CodeBlock
  lang="shell"
  title="Run this command in your `packages/app` directory"
  code={`yarn add @backstage/ui`}
/>

<CodeBlock
  lang="tsx"
  title="Add this line to `packages/app/src/index.tsx`"
  code={`import '@backstage/cli/asset-types';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@backstage/ui/css/styles.css'; // [!code ++]

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);`}
/>

<Banner
  text="Import these styles only once at your application root. Plugin developers should skip this step to avoid conflicts."
  variant="warning"
/>

## Use BUI components

As a plugin maintainer, you can use BUI components in your plugin. As mentioned above, you should not import the styles
again in your plugin as this will be handled at the root of your application. To get started, just add the library to
your plugin and import the components you need.

<CodeBlock
  lang="shell"
  title="Run this command in your `packages/[your-plugin]` directory"
  code={`yarn add @backstage/ui`}
/>

<CodeBlock lang="tsx" title="Let's get started 🚀" code={snippet} />

## BUIProvider

`BUIProvider` provides routing and analytics integration for all BUI components. It must be rendered inside a React Router context for client-side navigation to work in components like Link, ButtonLink, Tabs, Menu, TagGroup, and Table.

### Setup

If you're using the **new frontend system**, the provider is wired automatically via `@backstage/plugin-app` — no setup required.

For the **old frontend system**, the `BUIProvider` is included in the app shell from `@backstage/core-app-api` and works out of the box.

If you need to set up the provider manually (e.g. in a custom app shell), wrap your app content with the `BUIProvider` inside your Router and pass in Backstage's `useAnalytics` hook:

<CodeBlock lang="tsx" code={analyticsSetupSnippet} />

<Banner
  text="BUIProvider must be rendered inside a React Router context. If placed outside, components will fall back to full-page navigation instead of client-side routing."
  variant="warning"
/>

### Analytics

Once configured, BUI components with navigation behavior — Link, ButtonLink, Tab, MenuItem, Tag, and Row — fire a `click` event through Backstage's analytics system when a user navigates. Events include the link text as the subject and the destination URL in the attributes, along with any `AnalyticsContext` metadata (such as `pluginId`) from the component's position in the tree.

To suppress tracking on an individual component, use the `noTrack` prop:

<CodeBlock lang="tsx" code={analyticsNoTrackSnippet} />