or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

analytics-tracking.mdapi-system.mdconfiguration-access.mdcore-utilities.mdextension-system.mdindex.mdplugin-management.mdrouting-system.mdtranslation-system.md
tile.json

tessl/npm-backstage--core-plugin-api

Core API used by Backstage plugins for analytics, configuration, routing, and cross-plugin communication

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@backstage/core-plugin-api@1.10.x

To install, run

npx @tessl/cli install tessl/npm-backstage--core-plugin-api@1.10.0

index.mddocs/

Backstage Core Plugin API

The @backstage/core-plugin-api package provides the foundational API layer for developing Backstage plugins. It offers comprehensive APIs for analytics, application management, configuration, routing, extensions, and cross-plugin communication, enabling developers to build scalable and integrated plugin experiences within the Backstage ecosystem.

Package Information

  • Package Name: @backstage/core-plugin-api
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @backstage/core-plugin-api or yarn add @backstage/core-plugin-api

Core Imports

Main API (stable):

import {
  useApi,
  createApiRef,
  createPlugin,
  useRouteRef,
  createRouteRef,
  useAnalytics
} from '@backstage/core-plugin-api';

Alpha API (experimental):

import { 
  TranslationApi, 
  useTranslationRef,
  translationApiRef,
  appLanguageApiRef,
  AppLanguageApi
} from '@backstage/core-plugin-api/alpha';

CommonJS:

const { useApi, createApiRef, createPlugin } = require('@backstage/core-plugin-api');

Basic Usage

import {
  createPlugin,
  createApiRef,
  createRouteRef,
  useApi,
  configApiRef
} from '@backstage/core-plugin-api';

// Create a plugin
const myPlugin = createPlugin({
  id: 'my-plugin',
  routes: {
    root: createRouteRef({
      id: 'my-plugin:root',
    }),
  },
});

// Create and use an API
const myApiRef = createApiRef<MyApi>({
  id: 'plugin.my-api',
});

function MyComponent() {
  const configApi = useApi(configApiRef);
  const backendUrl = configApi.getString('backend.baseUrl');
  
  return <div>Backend URL: {backendUrl}</div>;
}

Architecture

The Backstage Core Plugin API is built around several key architectural patterns:

  • API System: Centralized dependency injection using ApiRef and ApiHolder for service discovery
  • Plugin Architecture: Modular plugin system with lifecycle management and feature flags
  • Routing System: Type-safe route definitions with parameter extraction and external route binding
  • Extension System: Component extension framework with error boundaries and lazy loading
  • Analytics Framework: Event tracking and context management for user behavior analysis
  • Context Providers: React context-based state management for app-wide concerns

Capabilities

API System

Core dependency injection and service discovery system for managing APIs across plugins and the Backstage application.

function useApi<T>(apiRef: ApiRef<T>): T;
function createApiRef<T>(options: { id: string }): ApiRef<T>;
function createApiFactory<T>(options: ApiFactoryOptions<T>): ApiFactory<T>;

interface ApiRef<T> {
  id: string;
  T?: T;
}

interface ApiHolder {
  get<T>(apiRef: ApiRef<T>): T | undefined;
}

API System

Plugin Management

Plugin creation, configuration, and lifecycle management for organizing Backstage functionality into modular units.

function createPlugin<
  Routes extends { [name in string]: RouteRef },
  ExternalRoutes extends { [name in string]: ExternalRouteRef }
>(options: PluginConfig<Routes, ExternalRoutes>): BackstagePlugin<Routes, ExternalRoutes>;

interface BackstagePlugin<
  Routes extends { [name in string]: RouteRef } = {},
  ExternalRoutes extends { [name in string]: ExternalRouteRef } = {}
> {
  getId(): string;
  getRoutes(): Routes;
  getExternalRoutes(): ExternalRoutes;
  getFeatureFlags(): PluginFeatureFlag[];
}

Plugin Management

Routing System

Type-safe routing with route references, parameter extraction, and cross-plugin navigation support.

function createRouteRef<Params extends { [param in string]: string }>(
  options: RouteRefOptions<Params>
): RouteRef<Params>;

function useRouteRef<Params extends { [param in string]: string }>(
  routeRef: RouteRef<Params>
): (params?: Params) => string;

function createExternalRouteRef<
  Params extends { [param in string]: string },
  Optional extends boolean = false
>(options: ExternalRouteRefOptions<Params, Optional>): ExternalRouteRef<Params, Optional>;

Routing System

Analytics Tracking

Event tracking, context management, and analytics integration for monitoring user interactions and plugin usage.

function useAnalytics(): AnalyticsApi;

interface AnalyticsApi {
  captureEvent(event: AnalyticsEvent): void;
}

interface AnalyticsContextValue {
  captureEvent(event: AnalyticsEvent): void;
  readonly tracker: AnalyticsTracker;
}

Analytics Tracking

Configuration Access

Configuration API for accessing Backstage configuration values with type safety and environment-specific settings.

interface ConfigApi {
  has(key: string): boolean;
  keys(): string[];
  get(key?: string): ConfigValue;
  getOptional(key?: string): ConfigValue | undefined;
  getString(key: string): string;
  getOptionalString(key: string): string | undefined;
  getNumber(key: string): number;
  getOptionalNumber(key: string): number | undefined;
  getBoolean(key: string): boolean;
  getOptionalBoolean(key: string): boolean | undefined;
  getConfig(key: string): Config;
  getOptionalConfig(key: string): Config | undefined;
  getConfigArray(key: string): Config[];
  getOptionalConfigArray(key: string): Config[] | undefined;
  getStringArray(key: string): string[];
  getOptionalStringArray(key: string): string[] | undefined;
}

Configuration Access

Extension System

Component extension framework for dynamic UI composition with error boundaries and lazy loading support.

function createExtension<T>(
  definition: ExtensionDefinition<T>
): Extension<T>;

interface Extension<T> {
  id: string;
  attachTo: AttachmentPoint;
  disabled?: boolean;
  component: React.ComponentType<T>;
}

Extension System

Core Utilities

Essential utilities for app integration, component data management, and element filtering.

function useApp(): App;
function attachComponentData<P>(
  component: ComponentType<P>,
  type: string,
  data: unknown
): ComponentType<P>;
function getComponentData<T>(
  node: ComponentType<any>,
  type: string
): T | undefined;
function useElementFilter<T>(
  node: ReactElement,
  filterFn: (elements: T[]) => T[]
): ElementCollection<T>;

Core Utilities

Translation System (Alpha)

Internationalization system for translating plugin content and managing app language preferences.

function useTranslationRef<TMessages extends Record<string, any>>(
  translationRef: TranslationRef<TMessages>
): TranslationFunction<TMessages>;

interface TranslationApi {
  getTranslation<TMessages extends Record<string, any>>(
    translationRef: TranslationRef<TMessages>
  ): Promise<TranslationFunction<TMessages>>;
}

interface AppLanguageApi {
  getAvailableLanguages(): { languages: string[] };
  setLanguage(language: string): void;
}

Translation System

Core API References

The package exports several key API references for commonly used services:

const configApiRef: ApiRef<ConfigApi>;
const analyticsApiRef: ApiRef<AnalyticsApi>;
const errorApiRef: ApiRef<ErrorApi>;
const storageApiRef: ApiRef<StorageApi>;
const featureFlagsApiRef: ApiRef<FeatureFlagsApi>;
const oauthRequestApiRef: ApiRef<OAuthRequestApi>;
const alertApiRef: ApiRef<AlertApi>;
const appThemeApiRef: ApiRef<AppThemeApi>;
const discoveryApiRef: ApiRef<DiscoveryApi>;
const fetchApiRef: ApiRef<FetchApi>;
const identityApiRef: ApiRef<IdentityApi>;

Alpha API References

Additional API references marked as experimental:

const translationApiRef: ApiRef<TranslationApi>;
const appLanguageApiRef: ApiRef<AppLanguageApi>;

Authentication Provider References

Pre-configured authentication provider API references:

const googleAuthApiRef: ApiRef<GoogleAuthApi>;
const githubAuthApiRef: ApiRef<GithubAuthApi>;
const oktaAuthApiRef: ApiRef<OktaAuthApi>;
const gitlabAuthApiRef: ApiRef<GitlabAuthApi>;
const microsoftAuthApiRef: ApiRef<MicrosoftAuthApi>;
const oneloginAuthApiRef: ApiRef<OneLoginAuthApi>;
const bitbucketAuthApiRef: ApiRef<BitbucketAuthApi>;
const bitbucketServerAuthApiRef: ApiRef<BitbucketServerAuthApi>;
const atlassianAuthApiRef: ApiRef<AtlassianAuthApi>;
const vmwareCloudAuthApiRef: ApiRef<VmwareCloudAuthApi>;

Types

type AnyApiRef = ApiRef<unknown>;
type AnyApiFactory = ApiFactory<unknown, unknown>;

interface PluginConfig<
  Routes extends { [name in string]: RouteRef } = {},
  ExternalRoutes extends { [name in string]: ExternalRouteRef } = {}
> {
  id: string;
  routes?: Routes;
  externalRoutes?: ExternalRoutes;
  featureFlags?: PluginFeatureFlag[];
}

interface PluginFeatureFlag {
  name: string;
}

type IconComponent = React.ComponentType<React.SVGProps<SVGSVGElement>>;