plugin-tools

plugin-tools copied to clipboard

Extracted from https://github.com/grafana/plugin-tools/issues/750 : "I would like to know what's required at minimum for a plugin to build and execute. This would hopefully allow me to shorten the duration of an npm install and reduce the overall file size during development."

Create plugin is an opinionated tool for scaffolding plugins. We aim to provide developers with everything they need to develop a plugin which follows our best practices. However, this does include a number of optional elements, not strictly required, and there can be valid reasons why they may wish to omit or remove certain libraries or generated files. Some optional elements we expose to developers as prompts in the tool - for example the levitate compatibility check, whilst flexibility can be useful - it also complicates matters and slows down the getting started workflow.

We have recently introduced the ability to pass flags to create-plugin to allow it to be run without using the interactive prompts.

After generating a (frontend only) plugin we provide the following success message:

## What's next?

Run the following commands to get started:

    * cd ./org-name-app
    * npm install to install frontend dependencies.
    * npm run dev to build (and watch) the plugin frontend code.
    * docker-compose up to start a grafana development server. Restart this command after each time you run mage to run your new backend code.
    * Open http://localhost:3000 in your browser to create a dashboard to begin developing your plugin.

Note: We strongly recommend creating a new Git repository by running git init in ./org-name-app before continuing.

    * Learn more about Grafana Plugin Development at https://grafana.com/developers/plugin-tools

We also provide this documentation on folder structure in the get started guide: https://grafana.com/developers/plugin-tools/#step-2-open-the-generated-folder-structure and more details in: https://grafana.com/developers/plugin-tools/get-started/folder-structure

Note: we are still gathering feedback on improving our documentation structure, any references or recommended placement is subject to change from that exercise.

### Tasks
- [ ] Document the flags in https://grafana.com/developers/plugin-tools/get-started/prompt-cli-reference
- [ ] Improve folder structure documentation to better explain optional elements which could be removed (and why they are there in the first place - i.e. why we recommend them)
- [ ] Remove prompts for the GitHub actions to reduce the number of questions a developer has to answer.

@josmperez - Should you own this issue, or wil @sympatheticmoose ? Either way, can we please triage so it isn't in our project as "Needs Triage"?

I've added myself and @sympatheticmoose as owners and updated the status to Backlog (Docs Team).

@tomglenn has developed a proposal for enhancing the folder structures docs.

Closing this as basically fixed by Anatomy of a plugin issue.

@josmperez I disagree - this specific issue is not fixed and will need a follow up PR to the anatomy of a plugin doc

I have marked the first subtask fixed because the CLI commands have had additional detail added, including info on how to bypass the prompts. Are there additional things that need to be said? Do we need to add a column for optional/required on the bypass options?

@sympatheticmoose - I created https://github.com/grafana/plugin-tools/pull/1240 to complete the 2nd subtask. Please collaborate to add more info you feel would be helpful.