[docs] Improve documentation for plugin authors

[jlengstorf]

Currently, the documentation for plugin authors is pretty sparse. On the contributing page, there's a single paragraph, and the plugins section of the docs is super high-level.

What I'm proposing in the short term

The docs should be updated to:

• Explain naming conventions for plugins (e.g. when should I use gatsby-plugin-* vs gatsby-transformer-*?)
• Explicitly explain what files can be contained in a plugin, and which APIs are available to plugins
• Create a boilerplate to create a consistent Gatsby plugin README experience

What I'm proposing in the medium term

• Write tutorials for each of the plugin types to show real examples of using the plugin APIs
• Add video tutorials to complement the written versions
• Find a way to work plugin documentation into the new plugins page being created in Plugin Library build fixes #3906

What I'm proposing in the long term

• Add a CLI tool that asks a few questions about the plugin you want to create and sets you up with the proper boilerplate
• Add plugin validation to ensure that a plugin is compatible with your Gatsby install (e.g. no conflicts, versions are compatible)

Did I miss anything here? I can get started on the short-term updates right away — would love to get any feedback from other folks who've written plugins:

• where did you get stuck?
• what questions did you have trouble finding answers to?
• how could Gatsby's docs make the plugin authoring experience more friendly?

This may need to be pulled into a project — "Improve the Plugin Discovery and Authoring Experience" — or maybe we can solve it all in a few issues.

What do you think?

[KyleAMathews]

This looks fantastic! Let me know how I can help!

[markmichon]

Looks good! I was thinking about building a "gatsby-plugin-starter" repo, but haven't had the time. I like the idea of a CLI to handle that too.

[jlengstorf]

@KyleAMathews I'll probably need your help double-checking the API/naming conventions write-ups to make sure I didn't miss anything.

@markmichon A starter repo would be fantastic, but I wonder if we'd need multiple versions? For example, a plugin to add third-party code (e.g. Google Analytics) is really different from a transformer or a data source plugin. 😕 (That's why I put this in the long term category. 😂)

[jlengstorf]

I've got a PR started at #4272 to tackle the short-term changes. Any feedback is welcome as I work toward getting this done.

[jlengstorf]

@KyleAMathews can a plugin provide a gatsby-config.js? If so, do docs exist on how that works (e.g. loading order, is that available site-wide or scoped to the plugin)?

[jlengstorf]

When/how is index.js used? In the vast majority of plugins it's a no-op, but in a few places it appears to do things (e.g. https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-contentful/index.js). I'm not super clear on how this is being handled under the hood, so I could use some guidance and/or a link to the source where this gets picked up.

[jlengstorf]

If I'm in the right place in the code, it looks like index.js isn't used in plugins, which is confusing given that gatsby-source-contentful exports one.

https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/load-plugins/validate.js#L94-L105

This also appears to answer my previous question about gatsby-config.js — it's not possible to add or modify the config from a plugin. (Please confirm this.) 😅

[pieh]

index.js is used when plugin exports something that user (or other plugin) might want to import in their code via require/import - it doesn't use any of gatsby apis and isn't run by gatsby itself

in your gatsby-source-contentful this was added to reuse graphql types in plugin that is currently under development ( https://github.com/gatsbyjs/gatsby/pull/4205/files#diff-7629f8c5bcb62e07dc5b843af493a8e3R80 ) that want to reuse some of already defined types

gatsby-source-filesystem will export utility function that will create File nodes from remote urls (that will be used by other plugins - for example gatsby-source-wordpress

this is not gatsby specific - just normal module export

[jlengstorf]

#4272 is ready for review. Only thing left to add is the boilerplate README, which might actually make more sense in a starter repo. It feels like it wouldn't fit on the docs page right now; would love some feedback on this.