Gatsby Cloud Docs

Creating an Example Repository

Table of Contents

An example repository should be an illustration of the best practices of both Gatsby and your product and source plugin. It should be well-documented and allow users to get up-and-running with your great product as quickly as possible. Let’s dive in.

Scaffolding a project

The first step when starting a Gatsby project is to use the gatsby new command to scaffold out a project. First, if you haven’t already, please ensure you have installed the Gatsby CLI; refer to the instructions on GatsbyJS.org. Once done, use the following command to create the project my-great-product.

gatsby new my-great-product

Also, ensure you change directories (cd) to the project you just created:

cd my-great-product

You can now begin working in the my-great-product project with the minimal amount of configuration required to begin working on a Gatsby project. This will be the foundation you build upon to implement your great Gatsby source plugin.

Adding your source plugin

By this point, it’s presumed that you’ve created a source plugin that can be installed via NPM. If you haven’t, please refer to “Creating a First-Class Source Plugin”.

Install Source Plugin

First, you need to install your source plugin:

npm install gatsby-source-my-great-product --save

This will create the folder node_modules/gatsby-source-my-great-product which contains, as you may expect, your source plugin! Next, we need to use this plugin, and we’ll do so with Gatsby’s configuration API: gatsby-config.js.

Configuring Source Plugin

Now that we’ve installed the plugin we need to inform Gatsby of the plugin’s existence. Edit gatsby-config.js with something like the below:

module.exports = {
  /* Existing content snipped */
  plugins: [
    {      resolve: `gatsby-source-my-great-product`,      options: {        /* Relevant options here, e.g. access token, space id, etc. */      },    },  ],
}

The key consideration here is that you must provide example options (that a user may fill out!) so that the user can authenticate to their data with any necessary API keys or tokens. As Gatsby Plugins are just Node packages that accept options, these will be unique to your specific source plugin, so please adjust accordingly!

Now that you’ve added your source plugin to package.json (and corresponding node_modules folder) and to gatsby-config.js, you can now progress to sourcing data and creating some content!

Creating Content

This section is somewhat necessarily a little light on prescriptive steps. The ultimate goal is to create a real-world representative usage of your data and querying that data with Gatsby’s GraphQL layer. Common examples may include:

  1. Creating a real product (e.g. a blog, an e-commerce application, etc.)
  2. Sourcing data on a page (e.g. the home page displaying “Hello from My Great Product”)
  3. Fetching images or other content to show off integration with Gatsby’s responsive images or some other feature

In any scenario, you will want to create content that allows your product to shine and allows your users to understand the value of your product, as well as use your product quickly, easily, and effectively.

Tips and Tricks

To make the example as reusable as possible, you will want to ensure that a user does not have to strip away layers of your example in order to get something useful. In other words, you want to focus on keeping the examples as non-opinionated as possible from a code standpoint. A concrete example would be implementing TypeScript. While this may be something that you prefer to use, it may not be generally applicable, and a consumer of the example repository who does not like TypeScript will be forced to strip this out, thereby increasing the time until the user can get to truly devloping and building. Some guidelines are effective:

  1. Focus on your product: Show your product in the best light possible. Have somethign unique to your plugin? Show it off!
  2. Minimize opinions: Focus on delivering the product, not selecting Library X, Y, and Z and Technique A, B, and C, both of which will likely need to be stripped away by the end user.
  3. Keep it Simple: To show your product off in the best light, you should focus on base-line use cases that most users will use. Don’t attempt to document each and every advanced option, this only adds complexity and ends up confusing users.

Document, and Document Some More

To get your users using this example and your product, you want to ensure that you remove as many barriers as possible. One key, and oftentimes overlooked, barrier is poor documentation. Ensure that your README.md contains set-up instructions, resources, and links to help enable a user get up-and-running as simply and quickly as possible. As an example, consider our documentation for our starters, for example gatsby-starter-default.

If your user is able to get up-and-running quickly with your example, you’ve created a compelling experience that they will love. You’ve created a fan and increased your audience for your great product. Wonderful!

Create a Repository

Finally, the simplest step and the last step! Now you just need to open-source it and create a GitHub repository.

  1. Create a GitHub Repository
    • Note: If you have a GitHub organization (e.g. MyAwesomeProduct), this can be preferable to using a personal account for this repository
  2. Set your origin to the newly created GitHub repo
    git remote add origin git@github.com:your-name/your-awesome-product-example.git
  3. Ensure you’ve added all staged content
    git add .
    git commit -m "feat: initial commit of my awesome product"
  4. Push to the remote repo
    git push origin master

Et voilà! We’re done! Now you can share this excellent example with your users, and Gatsby Cloud can use this example to help your users get up-and-running as quickly as possible. Wonderful!

Examples

As with anything new, it’s helpful to see some concrete examples to strive towards. We recommend checking out some of the following to serve as reference implementations of an example repository:

Additionally, consider checking out these Headless CMS starters.