grafana-jsx
A JSX library for creating JSON for Grafana.
Contents
About
There are several ways now to write Grafana dashboards as code, but none which allow you to do so with JSX - a syntax which is now very common for front-end development.
This repository provides a JSX pragma for Grafana dashboard JSON creation along with some core Grafana dashboard components that can be used to create dashboards written in JSX.
This allows you to define elegant, re-usable and composable components for your dashboards that will ultimately be transpiled to JSON that can be seemlessly imported into Grafana, either by copy and paste, Dashboard API or scripted dashboards.
Usage
Getting Started
Install this package using npm / yarn.
yarn add grafana-jsx
The recommended way to use this package is with JSX in your codebase. This can be achieved by using the @babel/plugin-transform-react-jsx and babel-plugin-jsx-pragmatic plugins.
Add the babel plugins to your codebase:
yarn add -D @babel/plugin-transform-react-jsx babel-plugin-jsx-pragmatic
And update your .babelrc
to use the JSX babel plugins:
You can now use JSX and JSX Fragments <></>
in your codebase and Babel will parse the JSX using the grafana-jsx
pragmas.
import Dashboard from "grafana-jsx"; const MyCustomDashboard = <Dashboard => <Panels> <Panel = = = /> <Panel = = = /> </Panels> </Dashboard>; ;
APIs
createObject
The createObject
method has been re-exported from the json-jsx package. Please refer to it's usage documentation for API details.
createGrafanaJsxString
createGrafanaJsxString
is a utility method for reverse engineering valid JSX from a Grafana dashboard JSON object.
Note that it relies on the JSON being passed to it being a Grafana dashboard JSON object, it will not successfully parse generic JSON into JSX that can be used with the createObject
JSX pragma.
import createGrafanaJsxString from "grafana-jsx";import fs from "fs"; /** * Evaluates to: * * `<Dashboard editable= * <Annotations> * <Annotation builtIn={0} datasource={"test-datasource-1"} enable= * <Annotation builtIn={1} datasource={"test-datasource-2"} enable= * </Annotations> * <Links> * <Link icon={"external link"} tags= * </Links> * <Panels> * <Panel type={"test-type-1"} x={0} y={0} w={12} h={9} /> * <Panel type={"test-type-2"} x={0} y={9} w={12} h={9} /> * </Panels> * <Templates enable={true}> * <Template allFormat= * </Templates> * <Time from={"now-12h"} to={"now-6h"} /> * <TimePicker collapse= * </Dashboard>` * * Note that the output JSX is quite verbose. You may be able to remove some / all * of the props assigned to components as they may well be defaults. * */const grafanaJsxString = ; /** * You can then write the output to a file for use as code. */ const dashboardFileContents = `import { Annotation, Annotations, Dashboard, Link, Links, Panel, Panels, Row, Template, Templates, Time, TimePicker} from "grafana-jsx"; const MyDashboard = ( ); export default MyDashboard;`; fs;
Options
Argument | Description |
---|---|
json | The Grafana dashboard JSON that you wish to convert to a string of JSX. |
Components
Annotation
Creates an annotation object.
const myAnnotation = <Annotation = = = = = = = />;
See the Grafana dashboard Annotation documentation for further details.
Annotations
Creates an annotations object. Expected to be composed with Annotation
components.
const myAnnotations = <Annotations> <Annotation /> </Annotations>;
See the Grafana dashboard Annotation documentation for further details.
Dashboard
Creates a Grafana dashboard object. Expected to be composed with other components.
const myDashboard = <Dashboard = = = = = = = = = > <Annotations> <Annotation /> </Annotations> </Dashboard>;
See the Grafana dashboard JSON documentation for further details.
Link
Creates a link object.
const myLink = <Link = = = />;
Links
Creates an links object. Expected to be composed with Link components.
const myLinks = <Links> <Link /> </Links>;
Panel
Creates a panel object.
const myPanel = <Panel = = = = = = = />;
See the Grafana dashboard Panels documentation for further details.
Panels
Creates an panels object. Expected to be composed with Panel components.
const myPanels = <Panels> <Panel /> </Panels>;
See the Grafana dashboard Panels documentation for further details.
Row
Creates a panel object of type row
. Expected to be composed with Panel components.
const myRow = <Row = = => <Panel /> </Row>;
See the Grafana dashboard Panels documentation for further details.
Template
Creates a template object.
const myTemplate = <Template = = = = = = = = = = = = = = = = = = = = = = />;
See the Grafana dashboard Templating documentation for further details.
Templates
Creates an templates object. Expected to be composed with Template components.
const myTemplates = <Templates => <Template /> </Templates>;
See the Grafana dashboard Templating documentation for further details.
Time
Creates a time object.
const myTime = <Time = = />;
See the Grafana dashboard JSON documentation for further details.
TimePicker
Creates a timepicker object.
const myTimepicker = <TimePicker = = = = = = = = />;
See the Grafana dashboard Timepicker documentation for further details.
Developing
Install
yarn install --frozen-lockfile
Build
yarn build
Test
Unit & Integration Tests
yarn test
Storybook
Start the Grafana JSX Storybook instance:
yarn storybook
Refer to the Storybook README for further information.
Lint
yarn lint
Contributing
Please check out the CONTRIBUTING docs.
Changelog
Please check out the CHANGELOG docs.