diff --git a/docusaurus/docs/get-started/best-practices.md b/docusaurus/docs/get-started/best-practices.md index cdbad0199..b0e9866c5 100644 --- a/docusaurus/docs/get-started/best-practices.md +++ b/docusaurus/docs/get-started/best-practices.md @@ -7,7 +7,7 @@ keywords: - plugins - plugin - best practices -sidebar_position: 10 +sidebar_position: 30 --- # Best practices for plugin development diff --git a/docusaurus/docs/get-started/folder-structure.md b/docusaurus/docs/get-started/folder-structure.md deleted file mode 100644 index d03b245be..000000000 --- a/docusaurus/docs/get-started/folder-structure.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -id: folder-structure -title: Folder structure -description: How your folder structure should look after running create-plugin. -keywords: - - grafana - - plugins - - plugin - - create-plugin - - folders -sidebar_position: 60 ---- - -After you [Run](./get-started.mdx#run-the-create-plugin-tool) the `create-plugin` tool and have answered the prompts, your project should look similar to this: - -``` -myorg-myplugin-datasource/ -├── .config/ -├── .eslintrc -├── .github -│   └── workflows -├── .gitignore -├── .nvmrc -├── .prettierrc.js -├── CHANGELOG.md -├── LICENSE -├── Magefile.go -├── README.md -│   └── integration -├── docker-compose.yaml -├── go.mod -├── go.sum -├── jest-setup.js -├── jest.config.js -├── node_modules -├── package.json -├── pkg -│   ├── main.go -│   └── plugin -├── playwright.config.ts -├── src -│   ├── README.md -│   ├── components -│   ├── datasource.ts -│   ├── img -│   ├── module.ts -│   ├── plugin.json -│   └── types.ts -├── tsconfig.json -└── tests -``` - -## Required files - -You must have files with these exact filenames: - -| Filename | Description | -| ------------------- | -------------------------------------------------------------------------------------------------------- | -| `./go.mod` | Go modules dependencies. Refer to [Golang documentation](https://golang.org/cmd/go/#hdr-The_go_mod_file) | -| `./src/plugin.json` | A JSON file describing the plugin. | -| `./src/module.ts` | The entry point of the frontend plugin. | -| `./pkg/main.go` | The entry point of the backend plugin. | - -## Optional files - -These files in your project are optional: - -| Filename | Description | -| --------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `./Magefile.go` | We strongly recommend using mage build files so that you can use the build targets provided by the backend plugin SDK. | diff --git a/docusaurus/docs/get-started/get-started.mdx b/docusaurus/docs/get-started/get-started.mdx index bc3a6b5d1..fd7615a20 100644 --- a/docusaurus/docs/get-started/get-started.mdx +++ b/docusaurus/docs/get-started/get-started.mdx @@ -167,7 +167,7 @@ The file structure should look like this: └── tsconfig.json ``` -For more information about these files, refer to [Folder structure](/get-started/folder-structure/). +For more information about these files, refer to [Anatomy of a plugin](/key-concepts/anatomy-of-a-plugin/). ## Build and run your plugin in Docker diff --git a/docusaurus/docs/key-concepts/anatomy-of-a-plugin.md b/docusaurus/docs/key-concepts/anatomy-of-a-plugin.md new file mode 100644 index 000000000..ff687793f --- /dev/null +++ b/docusaurus/docs/key-concepts/anatomy-of-a-plugin.md @@ -0,0 +1,184 @@ +--- +id: anatomy-of-a-plugin +title: Anatomy of a plugin +description: This guide describes the anatomy of a plugin, including the individual components that make up each plugin type. +keywords: + - grafana + - plugins + - plugin + - create-plugin + - folders + - anatomy + - components + - apps + - data sources + - panels +sidebar_position: 0 +--- + +# Anatomy of a plugin + +Grafana plugins enable you to extend Grafana’s core functionality by adding custom features, such as new data sources, visualizations, or entire applications. + +This guide walks you through the essential components of a Grafana plugin, and how to structure and organize them. You'll learn about the folder structure generated by the `create-plugin` tool, and where to go next to learn how to build and extend a plugin using the scaffolded template. + +## Before you begin + +Before proceeding, we recommend reviewing the [plugin types and usage guide](/key-concepts/plugin-types-usage) to gain a basic understanding of the different types of plugins available. + +Each Grafana plugin is composed of several essential components that extend Grafana’s functionality in different ways. First, we’ll explore the core parts of each of the three primary plugin types: apps, data sources, and panels. + +![The different available plugin types: app, data source, and panel](./images/plugin-types.png) + +## App plugins + +App plugins provide maximum flexibility, allowing developers to build custom experiences that go beyond basic visualization or data interaction. They can include custom pages, backends for server-side logic, and UI extensions that hook into Grafana’s core functionality. + +![The components of an app plugin](./images/app-plugin.png) + +### Pages + +Apps can add custom pages accessible from the Grafana navigation. These pages are essentially React components that allow developers to create custom user interfaces. To add a page, developers can use the `PluginPage` component from the `@grafana/runtime` package. You can [learn more about adding pages to apps](/tutorials/build-an-app-plugin#add-a-page-in-the-navigation-menu) in our app tutorial. + +![An example custom app page](./images/app-pages.png) + +### Configuration + +App plugins often include configuration pages where users can input necessary settings like API credentials or other parameters. You can [learn more about adding configuration pages to apps](/tutorials/build-an-app-plugin#configuration-page) in our app tutorial. + +![An example app configuration page](./images/app-configuration.png) + +### UI extensions + +App plugins can register and expose UI extensions that hook into core Grafana features, providing additional functionality or interaction points. These extension points allow for powerful integrations with Grafana’s UI. You can [learn more about UI extensions](/how-to-guides/ui-extensions/) in our how-to guides. + +![An example panel visualization](./images/ui-extension.png) + +### Health check + +Apps can define health checks to ensure that the plugin is properly configured and operational. You can customize these checks based on the plugin’s backend logic. See our [example health check](https://github.com/grafana/grafana-plugin-examples/blob/7d761244d370ad91715c68e24e6d83852d8e5b11/examples/app-with-backend/pkg/plugin/app.go#L47) for implementation details. + +### Call resource + +Apps can have backends to handle server-side functionality, such as making external API calls or processing more advanced authentication methods. The `CallResourceHandler` method is commonly used for this purpose. See our [app with backend example](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/app-with-backend) for implementation details. + +### Nested plugins + +App plugins can bundle multiple plugins, such as data sources or panels, into a single installable package. This approach is useful for services that require a combination of plugins for full functionality. You can [learn more about working with nested plugins](/how-to-guides/app-plugins/work-with-nested-plugins) in our documentation. + +## Data source plugins + +Data source plugins allow Grafana to connect to external services, configure queries, and display data. They can include frontend-only or full-stack components (with a backend). + +![The components of a Data Source plugin](./images/data-source-plugin.png) + +### Config editor + +The config editor is where users provide connection details (for example, API keys, URLs) for the external service when configuring a specific instance of the data source. To define the config editor, use `setConfigEditor()` and pass a custom configuration component. You can see [how to define a config editor in our basic data source plugin example](https://github.com/grafana/grafana-plugin-examples/blob/main/examples/datasource-basic/src/components/ConfigEditor/ConfigEditor.tsx). + +Ensure that your sensitive data is stored securely using `secureJson`. Read our guide on [adding authentication for data source plugins](/how-to-guides/data-source-plugins/add-authentication-for-data-source-plugins#store-configuration-in-securejsondata) for more details. + +![An example Data Source config editor](./images/datasource-configeditor.png) + +### Query editor + +The query editor allows users to construct queries against the connected service. This editor is used when adding a panel in a dashboard, when using Explore, and when creating a new Alert Rule. Query editors can be customized to provide a [code editor](https://github.com/grafana/grafana/blob/main/packages/grafana-ui/src/components/Monaco/CodeEditor.tsx) as well as a guided query builder. You can see [how to define a query editor in our data source plugin example](https://github.com/grafana/grafana-plugin-examples/blob/main/examples/datasource-basic/src/components/QueryEditor/QueryEditor.tsx). + +![An example data source query editor](./images/datasource-queryeditor.png) + +### Health check + +The "Save and Test" button in the data source config page allows users to verify that the connection works. Plugins can customize this behavior by [adding custom health checks](/how-to-guides/data-source-plugins/convert-a-frontend-datasource-to-backend#health-check). + +![A data source health check being performed](./images/datasource-healthcheck.png) + +### Query data + +The `QueryData` method processes multiple queries and returns corresponding responses. Each query includes a `RefID`, which is mapped to its response in a `QueryDataResponse`. The method loops through the queries, processes them individually, and returns either the result or an error with an appropriate status code. + +This approach allows for efficient handling of multiple queries, with built-in logging and error management to ensure smooth operation. + +Take a look at the [QueryData implementation in our data source example](https://github.com/grafana/grafana-plugin-examples/blob/main/examples/datasource-http-backend/pkg/plugin/datasource.go#L99). + +### Call resource + +Custom endpoints allow a data source plugin to expose custom HTTP API routes for server-side functionality. This is particularly useful when dealing with authentication, advanced queries, or processing large datasets. You can create custom endpoints in the backend by using the `CallResourceHandler` method to handle requests and respond with data or status information. + +For an example of how to implement custom endpoints, refer to the [app with backend example](https://github.com/grafana/grafana-plugin-examples/blob/main/examples/app-with-backend/pkg/plugin/resources.go). + +## Panel plugins + +Panel plugins enhance Grafana by offering custom components that provide unique data visualizations or other useful widget-like functionality within dashboards. + +![The components of a panel plugin](./images/panel-plugin.png) + +### Visualization + +Panel plugins provide visual representations of data in Grafana dashboards. To create a custom visualization, developers use React components to define how data will be rendered on the dashboard. This visualization can be anything from a simple chart to a complex interactive widget. The panel’s `render()` function defines how the data is passed into the visualization and how updates are handled when data or options change. + +For more details on panel visualizations, refer to the [panel plugin example](https://github.com/grafana/grafana-plugin-examples/tree/main/examples/panel-basic). + +![An example panel visualization](./images/panel-visualization.png) + +### Panel options + +Panel options allow users to customize the behavior and appearance of the panel plugin. You can define these options by implementing the `OptionsEditor` component, which can expose options relevant to the visualization. These options are passed into the panel’s `render()` function, allowing for dynamic updates based on user inputs. + +You can see an example of how to implement panel options in the [basic panel example](https://github.com/grafana/grafana-plugin-examples/blob/main/examples/panel-basic/src/types.ts#L5). + +![An example of custom panel options on the right](./images/panel-options.png) + +## Plugin folder structure + +Run the `create-plugin` tool to generate a new folder for your plugin. The plugin folder follows a standard naming convention (for example, `organization-pluginName-pluginType`) and contains all the necessary files for building, running, and testing your plugin. + +Here's an overview of the folder layout and key files: + +``` +myorg-myplugin-datasource/ +├── pkg/ +│ ├── main.go +│ └── plugin/ +├── src/ +│ ├── module.ts +│ ├── plugin.json +└── tests/ +├── CHANGELOG.md +├── docker-compose.yaml +├── go.mod +├── package.json +├── LICENSE +├── Magefile.go +├── README.md +``` + +:::note + +The `create-plugin` CLI tool is constantly being improved and as such there may be minor differences between this documentation and your scaffolded plugin project. + +::: + +### Key plugin files + +The following files are crucial for your plugin's development and functionality: + +- **Frontend code** (`src/`): This directory contains all the frontend code for your plugin. The main files to be aware of here are `plugin.json` and `module.ts`. + - `plugin.json`: Stores [metadata about your plugin](/reference/plugin-json), including information like its description, supported Grafana versions, and dependencies. + - `module.ts`: The entry point for your plugin's frontend logic. +- **Backend code** (`pkg/`): If your plugin includes backend functionality, the code will reside in this directory, typically within `pkg/plugin/`. Backend plugins are written in Go, and `main.go` serves as the entry point for your backend logic. +- **Test files** (`tests/`): This folder contains your plugin’s test files, typically suffixed with `.spec.ts` for frontend tests. You can [learn more about testing your plugin](/e2e-test-a-plugin/introduction) in our E2E testing guide. +- **Other files**: + - `docker-compose.yaml`: Contains the Docker configuration for running a local development instance of Grafana. + - `CHANGELOG.md`: Documents the history of changes and updates made to the plugin. + - `README.md`: Provides an overview of the plugin, including installation instructions and usage guidelines. + +## Next steps + +Now that you have an understanding of the essential components of a Grafana plugin and the structure of the project, we have some resources to recommend: + +- **Tutorials**: Dive deeper into specific plugin development tasks with our [Grafana plugin tutorials](/tutorials). These guides will help you create and customize data sources, panels, and app plugins. +- **Plugin Examples**: Check out the [Grafana Plugin Examples repository](https://github.com/grafana/grafana-plugin-examples) on GitHub for sample projects showcasing various types of plugins. +- **Community**: Join the [Grafana Community](https://community.grafana.com/c/plugin-development/30) to get advice, share experiences, and seek help from other plugin developers. +- **Plugin Publishing**: When you’re ready to share your plugin, [learn how to publish a Grafana plugin](/publish-a-plugin/publish-a-plugin). + +These resources will guide you through the finer details of building, testing, and eventually publishing your plugin, ensuring you have a smooth development process. diff --git a/docusaurus/docs/key-concepts/images/app-configuration.png b/docusaurus/docs/key-concepts/images/app-configuration.png new file mode 100644 index 000000000..7f2f4beb8 Binary files /dev/null and b/docusaurus/docs/key-concepts/images/app-configuration.png differ diff --git a/docusaurus/docs/key-concepts/images/app-pages.png b/docusaurus/docs/key-concepts/images/app-pages.png new file mode 100644 index 000000000..e7c0567a9 Binary files /dev/null and b/docusaurus/docs/key-concepts/images/app-pages.png differ diff --git a/docusaurus/docs/key-concepts/images/app-plugin.png b/docusaurus/docs/key-concepts/images/app-plugin.png new file mode 100644 index 000000000..6eeef7a91 Binary files /dev/null and b/docusaurus/docs/key-concepts/images/app-plugin.png differ diff --git a/docusaurus/docs/key-concepts/images/data-source-plugin.png b/docusaurus/docs/key-concepts/images/data-source-plugin.png new file mode 100644 index 000000000..c7e657f25 Binary files /dev/null and b/docusaurus/docs/key-concepts/images/data-source-plugin.png differ diff --git a/docusaurus/docs/key-concepts/images/datasource-configeditor.png b/docusaurus/docs/key-concepts/images/datasource-configeditor.png new file mode 100644 index 000000000..96acec9e4 Binary files /dev/null and b/docusaurus/docs/key-concepts/images/datasource-configeditor.png differ diff --git a/docusaurus/docs/key-concepts/images/datasource-healthcheck.png b/docusaurus/docs/key-concepts/images/datasource-healthcheck.png new file mode 100644 index 000000000..40204dcbb Binary files /dev/null and b/docusaurus/docs/key-concepts/images/datasource-healthcheck.png differ diff --git a/docusaurus/docs/key-concepts/images/datasource-queryeditor.png b/docusaurus/docs/key-concepts/images/datasource-queryeditor.png new file mode 100644 index 000000000..8edc6090c Binary files /dev/null and b/docusaurus/docs/key-concepts/images/datasource-queryeditor.png differ diff --git a/docusaurus/docs/key-concepts/images/panel-options.png b/docusaurus/docs/key-concepts/images/panel-options.png new file mode 100644 index 000000000..f2667599b Binary files /dev/null and b/docusaurus/docs/key-concepts/images/panel-options.png differ diff --git a/docusaurus/docs/key-concepts/images/panel-plugin.png b/docusaurus/docs/key-concepts/images/panel-plugin.png new file mode 100644 index 000000000..077aa0f8a Binary files /dev/null and b/docusaurus/docs/key-concepts/images/panel-plugin.png differ diff --git a/docusaurus/docs/key-concepts/images/panel-visualization.png b/docusaurus/docs/key-concepts/images/panel-visualization.png new file mode 100644 index 000000000..f56d19f3f Binary files /dev/null and b/docusaurus/docs/key-concepts/images/panel-visualization.png differ diff --git a/docusaurus/docs/key-concepts/images/plugin-types.png b/docusaurus/docs/key-concepts/images/plugin-types.png new file mode 100644 index 000000000..6b994b869 Binary files /dev/null and b/docusaurus/docs/key-concepts/images/plugin-types.png differ diff --git a/docusaurus/docs/key-concepts/images/ui-extension.png b/docusaurus/docs/key-concepts/images/ui-extension.png new file mode 100644 index 000000000..73e4edc8e Binary files /dev/null and b/docusaurus/docs/key-concepts/images/ui-extension.png differ diff --git a/docusaurus/website/README.md b/docusaurus/website/README.md index 5927f6f69..94834075a 100644 --- a/docusaurus/website/README.md +++ b/docusaurus/website/README.md @@ -42,16 +42,17 @@ Insert the client-side redirect here: /plugin-tools/docusaurus/website/docusauru ``` { from: ['/something-that-does-not-exist', '/something-that-does-not-exist/testing'], - to: '/get-started/folder-structure', + to: '/key-concepts/anatomy-of-a-plugin', }, ``` -`from` - being the old location and `to` being the new one. You can have multiple `from` urls for a single `to` url. +`from` - being the old location and `to` being the new one. You can have multiple `from` urls for a single `to` url. To test that the redirect works prior to publishing the PR deploy your branch to DEV Stage of developer portal. You can do so by [running this action](https://github.com/grafana/plugin-tools/actions/workflows/deploy-to-developer-portal-dev.yml) called `Deploy to Developer Portal DEV Bucket`. Hit the `run workflow` button and choose following parameters: + - Use workflow from: Branch `main` (keep it as it is by default) - Which branch to use? Here you should enter your branch name. -- Hit the `run workflow` button \ No newline at end of file +- Hit the `run workflow` button