JSX library for creating JSON for Grafana.
npm install grafana-jsxA JSX library for creating JSON for Grafana.
- About
- Usage
- Getting Started
- APIs
- createObject
- createGrafanaJsxString
- Options
- Components
- Annotation
- Annotations
- Dashboard
- Link
- Links
- Panel
- Panels
- Row
- Template
- Templates
- Time
- TimePicker
- Developing
- Install
- Build
- Test
- Unit & Integration Tests
- Storybook
- Lint
- Contributing
- Changelog
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.
Install this package using npm / yarn.
``console`
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:
`console`
yarn add -D @babel/plugin-transform-react-jsx babel-plugin-jsx-pragmatic
And update your .babelrc to use the JSX babel plugins:
`json`
{
"plugins": [
[
"@babel/plugin-transform-react-jsx",
{
"pragma": "jsx",
"pragmaFrag": "jsxFrag"
}
],
[
"babel-plugin-jsx-pragmatic",
{
"module": "grafana-jsx",
"import": "jsx",
"export": "createObject"
},
"jsx"
],
[
"babel-plugin-jsx-pragmatic",
{
"module": "grafana-jsx",
"import": "jsxFrag",
"export": "Fragment"
},
"jsxFrag"
]
]
}
You can now use JSX and JSX Fragments <> in your codebase and Babel will parse the JSX using the grafana-jsx pragmas.
`jsx
import { Dashboard } from "grafana-jsx";
const MyCustomDashboard = (
);
export default MyCustomDashboard;
`
#### 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.
`jsx
import { createGrafanaJsxString } from "grafana-jsx";
import fs from "fs";
/**
* Evaluates to:
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
* 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 = createGrafanaJsxString(
datasource={"test-datasource-1"}
name={"test-name-1"}
/>
datasource={"test-datasource-2"}
name={"test-name-2"}
/>
);
/**
* 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 = (
${grafanaJsxString}
);
export default MyDashboard;;
fs.writeFile("my-test-dashboard.js", dashboardFileContents, (error) => {
if (error) {
return console.error(error);
}
console.log("Dashboard JSX file succesfully written!");
});
`
##### Options
| Argument | Description |
| -------- | ----------------------------------------------------------------------- |
| json | The Grafana dashboard JSON that you wish to convert to a string of JSX. |
#### Annotation
Creates an annotation object.
`jsx`
const myAnnotation = (
datasource={"myDatasource"}
enable={true}
hide={false}
iconColor={"green"}
name={"annotation-1"}
type={"dashboard"}
/>
);
See the Grafana dashboard Annotation documentation for further details.
#### Annotations
Creates an annotations object. Expected to be composed with Annotation components.
`jsx`
const myAnnotations = (
);
See the Grafana dashboard Annotation documentation for further details.
#### Dashboard
Creates a Grafana dashboard object. Expected to be composed with other components.
`jsx`
const myDashboard = (
hideControls={false}
graphTooltip={0}
refresh={null}
style={"light"}
tags={["dashboard-tag-1"]}
title={"my-dashboard-title"}
timezone={"browser"}
uid={null}
>
);
See the Grafana dashboard JSON documentation for further details.
#### Link
Creates a link object.
`jsx`
const myLink = ;
#### Links
Creates an links object. Expected to be composed with Link components.
`jsx`
const myLinks = (
);
#### Panel
Creates a panel object.
`jsx`
const myPanel = (
title={"myPanel"}
x={0}
y={0}
width={12}
height={9}
options={null}
/>
);
See the Grafana dashboard Panels documentation for further details.
#### Panels
Creates an panels object. Expected to be composed with Panel components.
`jsx`
const myPanels = (
);
See the Grafana dashboard Panels documentation for further details.
#### Row
Creates a panel object of type row. Expected to be composed with Panel components.
`jsx`
const myRow = (
);
See the Grafana dashboard Panels documentation for further details.
#### Template
Creates a template object.
`jsx`
const myTemplate = (
allValue={null}
current={null}
datasource={null}
definition={null}
hide={0}
includeAll={false}
label={null}
multi={false}
multiFormat={null}
name={"region"}
options={[]}
query={null}
refresh={0}
regex={null}
skipUrlSync={false}
sort={0}
tagValuesQuery={null}
tags={[]}
tagsQuery={null}
type={"query"}
useTags={false}
/>
);
See the Grafana dashboard Templating documentation for further details.
#### Templates
Creates an templates object. Expected to be composed with Template components.
`jsx`
const myTemplates = (
);
See the Grafana dashboard Templating documentation for further details.
#### Time
Creates a time object.
`jsx`
const myTime = ;
See the Grafana dashboard JSON documentation for further details.
#### TimePicker
Creates a timepicker object.
`jsx`
const myTimepicker = (
enable={true}
notice={false}
now={true}
refreshIntervals={[
"5s",
"10s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"1d",
]}
timeOptions={["5m", "15m", "1h", "6h", "12h", "24h", "2d", "7d", "30d"]}
status={"Stable"}
type={"timepicker"}
/>
);
See the Grafana dashboard Timepicker documentation for further details.
`console`
yarn install --frozen-lockfile
`console`
yarn build
#### Unit & Integration Tests
`console`
yarn test
#### Storybook
Start the Grafana JSX Storybook instance:
`console`
yarn storybook
Refer to the Storybook README for further information.
`console``
yarn lint
Please check out the CONTRIBUTING docs.
Please check out the CHANGELOG docs.