Gatsby: Starter for creating source plugins

[ajayns]

Summary

I've been reading through the Source Plugin Tutorial. It's great, I love the narrative approach to building a plugin, but the problem is when it comes to the part where it should explain how to publish on npm, it lacks a bit and is not very helpful.

Basic example

I can recommend two things to improve the docs here:
One would be to add a short section on how a source-plugin published to npm would look like and how to convert the current plugin for publishing (maybe even test with npm link)
Another things would be a Starter for source plugins it could have babel compilation, testing and such already setup for the ease of the user.

Motivation

The primary goal is that, the user can get to code as soon as possible and understand how things work in the simplest of the ways. A starter for source plugins would mean you could understand what's happening by taking a glance at the structure and running it and also it makes kickstarting source-plugin development super fast.

[kakadiadarpan]

@ajayns I agree with you about the Starter for source plugins, that would be amazing to have.

Could you share more information about the following:

how a source-plugin published to npm would look like?
how to convert the current plugin for publishing?

[ajayns]

I'm not actually sure of those questions as I haven't read anything that recommends anything regarding them, but recently I've worked on a source plugin for Plone and will share a couple of things I figured then.

How a source plugin published to npm would look like?

I'm unaware of any structure recommended by the Gatsby community so the setup I used was a gatsby-node.js that's transpiled by Babel (this enables support for latest ES6+ features), another js file for helper functions (functions are exported here, making it easy for tests to be written), Jest for testing. This we came up with looking at a couple of plugins that were popular. Take a look at what I'm talking about: https://github.com/collective/gatsby-source-plone/
As I mentioned, I'm not sure about what's recommended, this is just what works for us, please do let me know if I'm wrong and I can improve on this.

How to convert the current plugin for publishing?

This answer would be pretty easy by just mentioning what all files a gatsby-source plugin would include: which primarily is the gatsby-node.js. An example structure of plugin with explanation for use of each file should be enough to figure out the rest.

[pieh]

I think skeleton/scaffold for plugins is good idea - i could see at least 2 templates - for source and transform plugins. For packages in gatsby repo we have plop template but this relies on gatsby repo babel setup, so for standalone plugins we would need something different.

I wonder if it would make sense to reuse gatsby-cli for it - ie. gatsby new gatsby/gatsby-source-plugin-starter gatsby-source-somename? (gatsby new just clones repo and install deps). This way we could reuse already existing tools and we would "just" need to create starter for it - with basic structure, .gitignore, .npmignore, babel config, jest config, maybe basic eslint too.

/cc @jlengstorf

I'm not sure about actual publishing to npm if this is something we need to cover as there is nothing special about gatsby packages when it comes to npm (so any "how to publish to npm" 3rd party tutorial or just npm docs would work here). Dev workflow with npm link might be good idea - but I think we can find some good sources out there for it too

[jlengstorf]

There's a discussion about a similar concept (plugin _management_) in the RFC stage right now: https://github.com/gatsbyjs/rfcs/pull/13

I would love to see the initial scaffolding get baked into the CLI. I think @pieh's suggestion for using the existing CLI setup is good, assuming we have a repo that's a good starter for source plugins. In the future I'd love to make the CLI a little more interactive and helpful, but that's probably out-of-scope for this discussion.

On a related note, I'm in the process of drafting a course for egghead.io that will cover exactly this, so I can potentially make the source starter repo as part of that coursework. We'll also be adding the course videos to the docs once they're ready. ETA on the course isn't confirmed yet, but I'm aiming for early 2019.

[moonmeister]

I just built a plugin and the lack of docs has been obvious. Happy to help with this. Struggle points were mostly as have been mentioned. All plugins in the Gatsby repo use Gatsby build/lint/jest configs and thus it's hard to determining what config you need (I'm also new to using/configuring these things period). I'm also new to npm and struggled with realizing I needed to build before publishing and what files could be excluded with .npmignore and what needed to be kept. like has been said, a repo would be a good step, and some general docs could be very useful as well for plugin authoring.

I don't think I've said anything revolutionary here that hasn't been said above. But, as someone who is going through this process currently...I'm saying...I agree, this is needed.

[gatsbot[bot]]

Old issues will be closed after 30 days of inactivity. This issue has been quiet for 20 days and is being marked as stale. Reply here or add the label "not stale" to keep this issue open!

[jlengstorf]

Not stale. I’m just slow. 😢

[marcysutton]

Hi everyone, we could definitely use some help here. @DSchau is planning to work a some plugin authoring tutorial update, but it has stalled for internal reasons. @shannonbux did some work in the plugin docs in the past few months – but we could still use some docs for publishing (not including Gatsby monorepo stuff - as that won't apply to most plugin authors). I see this stub, if anyone can pick it up for updates it would certainly help everyone: https://www.gatsbyjs.org/docs/maintaining-a-plugin/

A plugin starter sounds like a good idea too. A quick search turned up this one from the community, I think there needs to be an official Gatsby one though: https://github.com/devrchancay/gatsby-plugin-starter

If anyone wants to pick up either of those tasks, consider this open!