Skip to main content

Gatsby.js

Our biggest hope is that our tools will be as painless as possible to integrate into your existing projects. That's why we've built a custom plugin for integrating TakeShape with Gatsby projects!

To get started using our plugin, you'll need your Project ID and API Key.

Getting a Project ID and API Key#

If you haven't created a project yet, you can follow our guide to do that now.

Finding your Project ID#

The simplest way to find your project ID is to navigate to your project dashboard in the TakeShape web client. You can find and copy your project ID in the lower left.

Now all you need is your API Key!

Finding your API Key#

To get an API Key, you'll have to navigate to your project page in the TakeShape web client. First you'll log in, then you'll select the appropriate project. If you have to create a project, follow this doc for more information.

Click the API tab in the navbar at the top of your project page. On the left, you'll see an option that says API Keys. Click that, and you should see a button in the top-right of this page that says New API Key.

Press that button to begin.

You will see a small form that asks for a Title and Permissions. You can choose whatever title you want, but for permissions you should choose dev. The dev option will give you all the permissions you need to unlock the full power of TakeShape's Gatsby plugin!

Click the Create API Key button on the top right.

You will immediately see a popup message confirming the creation of your API Key. For security purposes, you won't ever get to see this API key again. Take good care of it!

Once you've copied your API Key, click "I understand and have copied my API key".

Done! Now you're ready to integrate your project into your Gatsby project through TakeShape's Gatsby plugin.

Installation#

The first step to integrating TakeShape's plugin with your Gatsby project is installing it. TakeShape currently supports use with versions 2 and 3 of Gatsby. Choose one of the following commands based on whichever version you're using:

Gatsby 3.x

npm install --save gatsby-source-takeshape

Gatsby 2.x

npm install --save gatsby-source-takeshape@1

Configuration#

Next, you'll need to configure your project to recognize TakeShape as a plugin. Your Gatsby project uses a gatsby-config.js file to define what metadata, plugins and other information your site should use. If you created your project with the gatsby new command, it should already have a gatsby-config.js file.

Don't see the file? Check out the Gatsby documentaion on config files to troubleshoot.

Setting up your configuration file#

Your Gatsby configuration file is a JS module that exports an object containing your configuration properties. Your file should contain:

gatsby-config.js
module.exports = {
//Your Options Here
}

We will be adding options to the object that your config file exports, but in order to properly use TakeShape, your Gatsby site needs access to your TakeShape project's ID, as well as one of your project's API Keys.

Caution

Your project information needs to be protected from public access! Uploading your Project ID and API Key from TakeShape to a public repository will expose your TakeShape project to access from anyone.

Protecting your TakeShape Project information with environment variables#

Let's configure environment variables to avoid security issues. Install dotenv.

npm install --save dotenv

Now on the first line of your gatsby-config file, add this:

gatsby-config.js
require('dotenv').config()

Create and open a .env file in the root of your project, then add the below code:

TAKESHAPE_PROJECT=<paste project id here>
TAKESHAPE_TOKEN=<paste API key here>

Now you'll be able to import these details into your gatsby-config file safely.

Caution

Make sure .env is included in your .gitignore so you don't accidentally commit your API key and Project ID!

Adding your TakeShape Project to your configuration file#

In your config file, add a plugins property with an array as its value. Create an object in the array, and give this object the properties resolve and options. Set resolve to 'gatsby-source-takeshape', and options to an object which will hold your API Key and TakeShape Project ID.

The properties should be apiKey and projectId. You can hardcode the API key and project ID here or you could use environment variables (we recommend the latter).

gatsby-config.js
module.exports = {
plugins: [
{
resolve: 'gatsby-source-takeshape',
options: {
apiKey: process.env.TAKESHAPE_TOKEN,
projectId: process.env.TAKESHAPE_PROJECT,
},
},
],
}

Other options#

The apiKey and projectId properties are not the only things you can configure in your TakeShape plugin. Below is a list of other options, along with explanations of what they do and why you would use them.

NameTypeDescription
apiKeystringYour API Key from your project. You'll need dev or ci permissions. Create in the API section of your project page. Click here to learn more.
projectIdstringYour project ID from your TakeShape project. Click here to learn more.
batchbooleanSet to true to batch queries that happen around the same time. By default, each query is a separate network request. See gatsby-source-graphql for more performance tuning tips. Default: false.
fetchOptionsobjectAdditional options to pass in with the second argument to fetch.
dataLoaderOptionsobjectAdvanced. Override or set options passed to Dataloader. Dataloader is used if batch is true.
throttlebooleanThrottle queries based on the x-ratelimit-limit response header. Enabling throttling will slow down your build, but will reduce the risk of hitting your API rate limit. Regardless of throttling, 429 errors are handled with exponential backoff. Default false.

Making Queries#

Now that you're all set up with the plugin, let's talk about using it!

There are two main ways to query TakeShape from your Gatsby project: Image queries and Data queries. Let's start with Data.

Data Queries#

Data queries allow you to make API requests to your TakeShape project schema. If you've connected external API's and services, the TakeShape plugin will allow you to interface with those services through your own custom-made queries and mutations defined in your schema.

Read the docs on editing schemas to learn more.

Assuming you have defined a getHelloWorld query in your project's schema, you could define that query in your code as shown in the example below.

import React from 'react'
import {graphql} from 'gatsby'
export const query = graphql`
query {
takeshape {
helloWorld: getHelloWorld {
content
}
}
}
`
const ExampleComponent = ({data}) => <>{data.takeshape.helloWorld.content}</>
export default ExampleComponent

The data would be returned as a property of data.takeshape, with the name of the data set to whatever you put prior to the colon. In the above example, we've defined our property as helloWorld.

For more advanced examples of data queries, check out the shape-portfolio-gatsby project.

tip

Need a sandbox to test out your queries in? Check out TakeShape's API Explorer.

Image Queries#

You can use Gatsby's GraphQL queries to pull objects suitable for use with the gatsby-image plugin. TakeShape's fixed and fluid fields will provide objects that support the base64 blur up effect, provide srcSets for responsive images, and offer faster page loads.

Because of limitations in how Gatsby handles third-party schemas, you must include the path field on your image queries for the fixed and fluid fields to work properly.

Caution

TakeShape's plugin does not currently support gatsby-plugin-image.

Below are some examples of how you would make image queries with the fixed or fluid fields.

Fixed image example#

ExampleComponent.jsx
import React from 'react'
import Img from 'gatsby-image'
export const query = graphql`
query ItemQuery {
takeshape {
item: getItem {
title
image {
path
fixed(width: 400, height: 400) {
...GatsbyTakeShapeImageFixed
}
}
}
}
}
`
const ExampleComponent = ({data}) => (
<>
<h1>{data.takeshape.item.title}</h1>
<Img fixed={data.takeshape.item.image.fixed} />
</>
)
export default ExampleComponent

Fluid image example#

ExampleComponent.jsx
import React from 'react'
import Img from 'gatsby-image'
export const query = graphql`
query HomepageQuery {
takeshape {
item: getItem {
title
image {
path
fluid(maxWidth: 400, maxHeight: 400) {
...GatsbyTakeShapeImageFluid
}
}
}
}
}
`
const ExampleComponent = ({data}) => (
<>
<h1>{data.takeshape.item.title}</h1>
<Img fluid={data.takeshape.item.image.fluid} />
</>
)
export default ExampleComponent

Image query args#

You can find a list of all available image query args by checking TakeShape's type defs here. You may notice in the type defs that there is an arg called imgixParams. This argument takes any set of valid imgix filters as a param-formatted string.

For example: crop=faces,edges&txt=Hello%20World!

Development and Testing#

The TakeShape Gatsby plugin must be run from within a Gatsby project.

Still confused? Ask for help!