@grafana/alerting

@grafana/alerting is Grafana Labs’ own package of types, utilities, React components, and hooks for working with the Grafana alerting system. It lives inside the grafana/grafana monorepo (packages/grafana-alerting) and is meant to be the shared foundation for alerting-related features across Grafana core and its plugins, rather than a general-purpose alerting SDK for arbitrary backends.

It covers the core mechanics of Alertmanager-style routing: representing a notification policy tree, matching label sets against routes with the same left-to-right depth-first traversal semantics as Alertmanager, computing inherited route properties (receiver, grouping, timing), and rendering the resulting UI (route selectors, contact point pickers, alert state icons, label chips) as ready-to-use React components.

The package is explicitly marked ALPHA by its maintainers — its public API is still settling and breaking changes are expected before Grafana Labs considers it stable enough to document for external consumption, even though it is already published to npm as part of the monorepo’s regular release cadence.

What You Get

• Label-matcher evaluation (=, !=, =~, !~) that mirrors Alertmanager’s own anchored-regex matching semantics
• A depth-first route-tree matcher (findMatchingRoutes, matchInstancesToRoute) that resolves which notification policy handles a given set of alert labels, including the continue flag’s fall-through behaviour
• Route property inheritance (getInheritedProperties, computeInheritedTree) for receiver, group_by, group_wait, group_interval, and repeat_interval
• React hooks (useMatchInstancesToRouteTrees) and components (RoutingTreeSelector, ContactPointSelector, AlertLabel, AlertLabels) ready to drop into a Grafana plugin UI
• A /testing entrypoint with Faker-backed mock factories for routing trees, contact points, and alert instances to use in consumer test suites

Common Use Cases

• A Grafana plugin author building a custom alerting or on-call UI that needs to show which notification policy will fire for a given alert
• Rendering a contact-point picker or routing-tree editor inside a Grafana app plugin without re-implementing Alertmanager’s matching rules
• Diagnosing why a particular alert instance routed to an unexpected receiver, using the matchingJourney trace returned by the matcher
• Writing unit or integration tests against alerting UI using the package’s own /testing mock factories instead of hand-rolled fixtures

Under The Hood

Architecture The package is organized by alerting concern under src/grafana/ — notificationPolicies (route-tree matching and inheritance), contactPoints, rules (alert state components), matchers (label predicate evaluation), and api (generated/RTK-Query-backed clients) — with a narrow, explicitly-curated src/index.ts barrel that re-exports only what the maintainers consider stable public API, plus separate /unstable, /internal, and /testing entrypoints for everything else; this deliberately keeps most of the implementation private even though the whole package ships to npm, and the route matcher itself is a recursive depth-first tree walk (findMatchingRoutes) that threads a matchingJourney accumulator through recursion so callers can diagnose exactly which policies were considered, not just which one matched.

Tech Stack TypeScript library built with tsc + Rollup (dual CJS/ESM output via rollup-plugin-esbuild), targeting React 19 and Redux Toolkit as peer/runtime dependencies, and depending on sibling monorepo packages (@grafana/api-clients for generated Alertmanager/notifications API clients, @grafana/i18n) alongside lodash, tinycolor2, and @faker-js/faker (used only for the /testing mock factories); it is built and versioned in lockstep with the rest of grafana/grafana via Nx (project.json) rather than as an independently-released package.

Code Quality Testing is extensive and taken seriously: the notification-policy matching logic alone has a 1000+ line test file covering inheritance edge cases and route-selection semantics, UI components carry co-located .test.tsx files plus Storybook .story.tsx/.mdx docs and .scenario.ts fixtures for interaction testing, and the code is fully typed with exported result/detail types (RouteMatchResult, LabelMatchDetails) rather than loose objects; a handful of @ts-ignore comments around generic reduce/type-narrowing edge cases and the package’s own ALPHA label are the main quality caveats.

API Design The public surface is intentionally small and curated — a handful of named exports for matching, route-tree utilities, and two label components — with everything else pushed behind /unstable or /internal so consumers can’t accidentally depend on implementation details; the trade-off is that a plugin author wanting the routing-tree or contact-point React components today has to reach into /unstable, since those aren’t part of the stable . export yet, which is consistent with the maintainers’ explicit warning that the package isn’t ready for general external consumption.