Gatsby: Creating a custom source

[aidanayala]

Is there anywhere I can find more detailed documentation on creating a gatsby-source plugin other than here https://www.gatsbyjs.org/docs/create-source-plugin/?

[calcsam]

Unless Google is helpful, that's all the official documentation that exists right now. However, you could look at some of the official plugins: https://github.com/gatsbyjs/gatsby/tree/master/packages

[aidanayala]

Yeah. I've been trying to pick apart how some of the other source plugins work. I've follow a similar pattern, creating a gatsby-node.js file. However nothing seems to get loaded in.

[markmichon]

I've been meaning to write a tutorial for this, and then update the docs accordingly. The reason it's somewhat hard to follow is that all the steps before createNode are unique to the source. A good way to think of the flow is: fetch external data => parse and format into a gatsby node => create the node via createNode.

The createNode docs are the really useful part of creating a new source.
Most of the properties are explained and self-explanatory, but here are a few things that stood out when I was recently building one:

• The content digest is how gatsby knows if things changed, so do what all the other plugins do by using the crypto library as per the examples, and pass in any of the useful field data to it.
• Type is the identifier for your plugin or aspect of your plugin. Choose an appropriate name.
• The fields can be anything you like, but some are reserved(ish): id, parent, children, etc as shown in the docs. For instance, ID has to be unique to the node, so if your ids from the source aren't unique (like if you are mixing two apis that might both have content with similar IDs, it can be useful to generate a fresh one.
• That return at the end of the exports.sourceNodes is important.

How you approach all of this is up to you. Some source plugins are more authentic in that they create nodes with fields for all the data. I've seen others that just grab the data, make a single node, and throw all the data into an object inside a single field.

[KyleAMathews]

Yeah, the docs page could use a lot more work. The difficulty in that page is that source plugins are more strongly influenced by what they're pulling data from then Gatsby specific parts. But there's enough common patterns that we should do a better job documenting those.

[m-allanson]

I'd love to see (or write? 😄) a tutorial that works through building a real source plugin, to create a real Gatsby site for an existing data set.

Maybe it could be pulling from GitHub's REST API to build a one or two page site showing neat stats about Gatsby?

[KyleAMathews]

@m-allanson that'd be awesome!

[aidanayala]

Thanks for your responses.

Makes a lot more sense now - As you said fetching the data is unique and cannot really be documented. But @m-allanson a tutorial like would be great.

I'm creating a simple API in Laravel for content and I'd love to be able to bundle a source plugin for it. Just got a little lost on where to start with it.

[m-allanson]

I followed up on the threat of writing a source plugin tutorial! Check it out here:

https://www.gatsbyjs.org/docs/source-plugin-tutorial/

Thanks to @jlengstorf for writing the plugin this tutorial is based on :D

I'm going to close this issue, but improvements or additional docs on source plugins are always welcome 🙏

[riddla]

@aidanayala: did you end up writing a source plugin for your Laravel API?