Skip to content

Getting Started

Jump to bottom
github-actions[bot] edited this page Jun 27, 2026 · 1 revision

Getting Started

Installation

npm install @rxtx4816/cockpit-plugin-base-react

Peer dependencies required in your plugin:

npm install react react-dom i18next react-i18next

Bootstrapping your plugin

Every Cockpit plugin needs an entry point that initialises i18n, the dark theme, and mounts React. This package handles all of it:

// src/index.tsx
import "./i18n";
import "@rxtx4816/cockpit-plugin-base-react/dark-theme";
import { bootstrapPlugin } from "@rxtx4816/cockpit-plugin-base-react/bootstrap";
import App from "./App";

bootstrapPlugin(App);

bootstrapPlugin wraps your app in an ErrorBoundary and a ToastProvider, then mounts it into the #app element that Cockpit expects.

i18n setup

Create src/i18n.ts in your plugin:

import { initCockpitI18n } from "@rxtx4816/cockpit-plugin-base-react/i18n";

initCockpitI18n();

This sets up i18next with Cockpit's locale loading conventions so useTranslation() works throughout your plugin.

Shared tooling config

Extend from the base configs so all plugins stay consistent.

tsconfig.json

{
  "extends": "@rxtx4816/cockpit-plugin-base-react/tsconfig.base.json",
  "compilerOptions": {
    "paths": {}
  }
}

eslint.config.js

import { createEslintConfig } from "@rxtx4816/cockpit-plugin-base-react/eslint.config.base";

export default createEslintConfig();

Pass extra globals if your plugin uses custom Cockpit types:

export default createEslintConfig({ CockpitHttpClient: "readonly" });

vitest.config.ts

import { defineConfig } from "@rxtx4816/cockpit-plugin-base-react/vitest.config.base";

export default defineConfig();

Dark theme

Importing the dark-theme side-effect module is all that's needed. It listens for three signals and keeps the pf-v6-theme-dark class on <html> in sync:

  • localStorage key shell:style (values: "light", "dark", "auto")
  • The custom cockpit-style event dispatched by the Cockpit shell switcher
  • The OS-level prefers-color-scheme media query

No configuration required.

Clone this wiki locally