# Blazingly fast development with Gatsby and structured content

_We set out to make the best possible web development experience with Gatsby using structured content from our APIs. Here's what we made._

Using the `sanity source plugin` your team can collaborate content model iteration, front-end look and feel as well as the actual content itself – all in real-time with instant previews.

* Real-time (as in milliseconds) content preview in dev
* Cheap, :lightning: fast builds (single API call to stream content)
* No types and fields left out by accident
* Powerful [Portable Text](https://www.portabletext.org)
* ...all with minimal configuration.

## Quickly get started with structured content

What we love about Gatsby, is that it's so easy to get going. Just put your content in some Markdown files, and write your templates against the internal GraphQL API. As much as we love Markdown, it has some important limitations:

* Your text and images are contained to your website, and can't easily be used elsewhere
* You tend to use `dangerouslySetInnerHTML` to add the authored content to your site, leaving you little control over the most important part of your website, the content.
* You have to know Git in order to add and edit content

You guessed it, if files aren't the answer, you'll need an API. And to get a content API you need a Content Management System. And isn't that usually a bit of a hassle to set up?

Not really! If you pop into your terminal and put in `npm i -g @sanity/cli && sanity init` and come back to this blog, you're only minutes away from having a full-fledged headless CMS where you have complete control over the open source editing environment built in React, with a trouble-free real-time backend with some powerful APIs for both reading and writing. Where you can make as many forever free developer projects as you want – and pay as you go if you need a bit more resources for your projects, instead of the famous "steep tier jump".

We also made [a sample company website monorepo](TK) where you're up and running in minutes with both a configured backend and frontend – ready to be tweaked and tailored for your own needs and deployed on either Netlify or Now (or both if you want full redundancy 😀).

Let's take a closer look at the source plugin and what it does

## Minimal Configuration

Gatsby provides the least effort way to create a React based website with Sanity.io. The source plugin will automatically give you a comprehensive GraphQL API in Gatsby to all your content and types. We strongly recommend using the GraphiQL explorer to test queries and get familiar with the schema documentation. It's super useful!

To get started with the Gatsby source plugin, først install it in your Gatsby project with `npm` or `yarn`:

yarn add gatsby-source-sanity
# or
npm install gatsby-source-sanity --save

Once it's installed, add this configuration to `gatsby-config.js`:

module.exports = {
  // ...
  plugins: [
    // ...
    {
      resolve: 'gatsby-source-sanity',
      options: {
        projectId: '<yourProjectId>',
        dataset: '<yourDatasetName>',
        // add a token with read permissions
        // if your dataset is private
        // and/or if you want to include drafts
        token: process.env.YOUR_SANITY_TOKEN || 'your-token'
      }
    }
  ]
}

If you start Gatsby in developer mode (`npm run dev` or `yarn dev`) you can query your content from Sanity using GraphiQL located at [http://localhost:8000/___graphql](http://localhost:8000/___graphql).

## Instant Live Content Preview

![GIF/Video of preview]()

Albeit static site generators give huge benefits in terms of a fast end-user experience, the trade-off is that the site needs to rebuild everytime you make edits to the code or the content. Gatsby has already solved the code part by doing hot module replacement in development mode – but that doesn't include whatever new content that's made available through APIs.

When `watchMode: true` in the plugin configuration, the source plugin will set up a listener to the backend and inject any change in the document it sees. If you add additionally add a token with reading permissions and set `draftOverlay: true`, you will get all changes instantly. Besides being ~~kinda~~ very cool, this also makes it tenable for a team to collaborate on design, code, and content at the same time, across multiple devices.

## Cheap and fast builds

The source plugin uses [Sanity.io](https://www.sanity.io)'s [export API](TK), which streams all your accessible documents in one go, super fast. That's one API request for the content, and one for the schema every time you run the build process, independent of how much content or many pages you have. That means that you can build your gatsby site many ten thousands of times each month on the forever free developer plan (and there's an affordable pay-as-you-go if you happen to surpass that).

## The Power of Portable Text


While we understand the appeal of Markdown ([react-markdown](https://github.com/rexxars/react-markdown) is the child of one of our lead developers), it comes with limitations. Even cool permutations like [MDX](https://github.com/mdx-js/mdx) and processors like [remarked](https://github.com/remarkjs/remark) have some important constraints when it comes to how easy it is to sustain and reuse that content across projects.

That's why with [Sanity.io](https://www.sanity.io), rich text content is stored as [Portable Text](https://www.portabletext.org), deeply typed and highly structured. Not only does this enable you to offer a WYSIWYG experience for yourself and your authors without all the bloody mess, but you also can get rid of `dangerouslyInsertInnerHTML` in your Gatsby templates, and have total and effortless control of how different parts of your rich text content should be rendered. We provide you with a handy library for React that takes care of the defaults and lets you override whatever parts of the text content with your own React components.

EXAMPLE TK

## No accidental missing fields or types

Most source plugins generate a GraphQL schema inferred from whatever content is available at any given moment. Which means that types and fields can be missing depending on if the content is present or not. This can get a bit cumbersome to work with, and doesn't encourage a more controlled way of planning your content models.

If you deploy a GraphQL API for your Sanity project (`sanity graphql deploy` in your project folder), the plugin will automatically fetch the schema definition and try it best to make sure that all your types and fields are present.

The schema definition prevents your site from accidentally breaking if you delete a document which had the last occurrence of content for a given field. As far as we know, no other source plugin solves this problem as of today, but it should be noted that there's some awesome work being done in the Gatsby community to provide an official and better solution for this down the road.

## Full gatsby-image support

Sanity already comes with a [pretty capable and easy to use image pipeline](https://css-tricks.com/five-interesting-ways-to-use-sanity-io-for-image-art-direction/) on a superfast CDN with transforms on demand, but if you want to use the same frontend components with a mix of remote or local sources or prefer the functionality of the `gatsby-image` library, we have made it easy for you to leverage that. Additionally, you'll have access to all that handy image metadata, like aspect ratios, dimensions, color palettes, the optional EXIF data and geotags via the API.

## Sanity.io + Gatsby.js = Perfect JAMstack companions

Gatsby has already set high standards for developer experience by striking the balance between code and configuration. We have worked hard to make it as effortless as possible to use Sanity.io as a content backend with Gatsby, and we hope that you will enjoy building websites with this combo.

We're very excited to see whatever you do with it and welcome you to come with all your questions, feedback, and ideas in our [developer community](https://slack.sanity.io).