Recipes (How To) for Common Tasks and Setups

[shellscape]

Note: Issue template removed as this is a Repository Management, long-running issue for tracking and action.

With the migration of core plugins to this repo, we're starting to get a birds-eye view of the types of issues that people are running up against with popular plugins. The majority of support requests that make it through to the repo are asking for implementation help. And that seems to stem from a lack of consolidated direction and documentation.

As such, I propose that we create a directory within this repository to house recipes - also known as how-to guides - for common plugin tasks and setups or boilerplating. I've seen this approach be highly effective and recipes become a source of truth for users.

Some initial thoughts on the idea:

• recipes should have a README entrypoint with standard approach, formatting, and layout
• code within recipes should be formatted in similar ways
• recipes should be verbose, using natural language to present more of a conversation with the reader
• recipes should have a standard directory structure when additional files, folders are necessary, and code in files outside of the README should share repo formatting
• runnable recipes (those which have additional files and folders) should have dependencies maintained (we may need an additional script/github action/hook for this)

Questions

• should all recipes be runnable?
• can we get the REPL to support adding plugins to make recipes runnable?

Proposed Recipe Structure

Recipes to be nested within directories that reflect the short plugin name. e.g.

/recipes
  |__ commonjs
  |__ inject
  |__ run

Within each plugin's recipe directory, recipes should be well-named. In cases where there is a common theme or where it makes sense for a parent of similar recipes to exist, additional subdirectories would be acceptable. e.g.

/recipes
  |__ commonjs
      |__ preact
          |__ simple
          |__ replace-react-dom

Comments

Please share additional comments/thoughts. This proposal was inspired by #94 by @mjarkk. For a working recipe example/reference, please see https://github.com/shellscape/webpack-plugin-serve/tree/master/recipes.

/cc @rollup/plugin-contributors @rollup/plugin-maintainers @rollup/core

[lukastaegert]

I really love this, ideas like "we should really have this" have been crossing my mind many times before. Some thoughts from me:

• It would be nice to integrate this with the website. At the very least, we should add a link to the recipes. A cooler approach could be to have some meta information in a common format available in the folder of each recipe. This could be a JSON or markdown file containing a title and short description. Then we could automatically parse these files whenever the website is redeployed and add an auto-generated recipes section that gives a nice overview of what is available, linking to the actual recipes. There could also be a short guide on how to add new recipes to get more people involved. I can definitely help with setting up the automatic parsing and website update if we want something like that.
• It would also be nice if it would be easy to use at least some recipes as boilerplate, degit style. Problem with https://github.com/Rich-Harris/degit is that is does not appear to support nested paths, there is already an issue for that: Monorepos? Rich-Harris/degit#48 Unless Rich has some concerns, maybe we can also help with that. In any case, it would be nice to prepare the repo structure in a way to make this possible, e.g. so that in the future I could degit rollup/plugins/recipes/commonjs/preact/simple/boilerplate

[stale]

Hey folks. This issue hasn't received any traction for 60 days, so we're going to close this for housekeeping. If this is still an ongoing issue, please do consider contributing a Pull Request to resolve it. Further discussion is always welcome even with the issue closed. If anything actionable is posted in the comments, we'll consider reopening it.# Comment to post when closing a stale issue. ⓘ