The Grafana Basic App plugin sample demonstrates how to build a basic app plugin for Grafana with custom routing.
App plugins let you create a custom out-of-the-box monitoring experience with features such as custom pages, nested data sources, and panel plugins.
Grafana (and the app plugins are no exception) uses React Router. You can register a new route based on our examples by adding a new route constant in constants.ts#L6 and then use it in the App.tsx.
Example: App.tsx, constants.ts#L6
You can use URL parameters for any routes by appending them to the path in the <Route> component.
Example: App.tsx, PageThree.tsx
// URL parameters are identified by the colon syntax (":<parameter>")
// The "?" at the end marks the parameter as optional, in which case React Router also identifies this route if there are no parameters used.
<Route path={`${ROUTES.Three}/:id?`} element={<PageThree />} />Retrieve URL parameters:
import { useParams } from 'react-router-dom';
export const MyComponent = () => {
const { id } = useParams<{ id: string }>();
};You can hide the left sidebar and get access to the full width of the page by changing the layout of the <PluginPage> component.
Example: PageThree.tsx
import { PageLayoutType } from '@grafana/data';
// ...
export function YourPage() {
return (
<PluginPage layout={PageLayoutType.Canvas}>
// ...We recommend using Emotion to style your components as in the example above.
Example: PageThree.tsx#L10
More info on how to use @emotion/css
The easiest way is to use the useStyles2() hook to access the GrafanaTheme2 theme object.
Example: PageThree.tsx#L26
Documentation on the Grafana Theme
You can define pages that you want to add to the left sidebar menu under the includes section of your plugin.json.
Example: plugin.json
Structure of a page item:
// plugin.json
{
"includes": [
{
"type": "page",
// The text of the menu item
"name": "Page One",
// The link of the menu item (%PLUGIN_ID% will resolve the id of your plugin at build time)
"path": "/a/%PLUGIN_ID%",
// The role who can access this page
"role": "Admin",
// This tells Grafana to add this page to the left sidebar
"addToNav": true,
"defaultNav": true
}
]
}You can add a configuration page to your app to set custom configuration options that are going to be persisted for your plugin on the backend.
Configuration pages can also be used to save secrets that are no longer sent down to the client but which can be appended to your proxy requests by the backend.
Example: module.ts, AppConfig.tsx
Add a new form field under your AppConfig.tsx and make sure that you are setting it under the jsonData object.
The jsonData object is an arbitrary object of data that can be persisted for your plugin using the /api/plugins/${pluginId}/settings API endpoint.
Example: AppConfig.tsx
Secrets for plugins are stored in the secureJsonData object. This is an arbitrary object of data; however, its value will never be sent back to the frontend for security reasons.
Example: AppConfig.tsx
You can update plugin settings by sending a POST request to the /api/plugins/${pluginId}/settings API endpoint.
Example: AppConfig.tsx
Example payload:
{
enabled: true,
pinned: true,
// Arbitrary object of data for your plugin
jsonData: {
apiUrl: state.apiUrl,
isApiKeySet: true,
},
// Arbitrary object of data for plugin secrets
// (pass `undefined` if you don't want to override existing values)
secureJsonData: {
apiKey: state.apiKey,
}
}Below you can find source code for existing app plugins and other related documentation.