Gatsby
Our biggest hope is that our tools will be as painless as possible to integrate into your 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.
Follow along with this guide by checking out our starter project repo. Our starters let you instantly deploy a pre-configured TakeShape project.
Connecting to your TakeShape Project
To connect to your TakeShape project, you need your API Endpoint and an API key.
If you haven't created a TakeShape project yet, follow this guide to do so.
If you already have a project, your API Endpoint will be in the TakeShape web client. In the home tab, look for the "Useful Snippets" section.
Copy the API Endpoint and save it somewhere secure.
To get an API Key, you'll have to create one. Read our docs on creating an API Key here.
Configuring your plugins
Next, you'll need to configure your project to recognize either the Gatsby GraphQL plugin or our custom TakeShape 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 documentation 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:
module.exports = {
//Your Options Here
}
We'll add options to the object your config exports, but to use your TakeShape project's API, you'll need the project's ID and a valid API Key.
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:
require('dotenv').config()
Create and open a .env file in the root of your project, then add the below code:
TAKESHAPE_PROJECT=Your-Project-Id-Here
TAKESHAPE_TOKEN=Your-Token-Here
TAKESHAPE_ENDPOINT=Your-Endpoint-Here
Now you'll be able to import these details into your gatsby-config file safely.
Installing the TakeShape plugin
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
Adding the TakeShape plugin 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).
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.
| Name | Type | Description |
|---|---|---|
apiKey | string | Your API Key from your project. You'll need dev or ci permissions. Create in the API section of your project page. Select here to learn more. |
projectId | string | Your project ID from your TakeShape project. Select here to learn more. |
batch | boolean | Set 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. |
fetchOptions | object | Additional options to pass in with the second argument to fetch. |
dataLoaderOptions | object | Advanced. Override or set options passed to Dataloader. Dataloader is used if batch is true. |
throttle | boolean | Throttle 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. |
Adding the Gatsby GraphQL plugin to your configuration file
If you don't want to use our custom plugin, you can use Gatsby's own GraphQL plugin. In your gatsby-config.js, your config object should look like this:
module.exports = {
plugins: [
{
resolve: `gatsby-source-graphql`,
options: {
typeName: `TakeShape`,
fieldName: `takeshape`,
url: process.env.TAKESHAPE_ENDPOINT,
headers: {
Authorization: `Bearer ${process.env.TAKESHAPE_TOKEN}`,
},
},
},
],
}
Making Queries with Gatsby's GraphQL plugin
To use Gatsby's built-in GraphQL plugin, you'll need to import their custom useStaticQuery hook. Open your index.js component in the src/pages directory and add the following code:
import React from "react"
import { graphql, useStaticQuery } from "gatsby"
const ExampleComponent = ({data}) =>{
const takeshapeData = useStaticQuery(graphql`
query {
takeshape{
getProductList{
items{
_id
name
price
}
}
}
}`)
}
Now you just need to use it in your JSX template like this:
return (
<section>
<h1>Products:</h1>
<ul>
{
takeshapeData.takeshape.getProductList.items.map(
product=>(
<li key={product._id}>
{product.name}: {product.price}
</li>
)
)
}
</ul>
</section>
)
The whole file should look like this:
import React from "react"
import { graphql, useStaticQuery } from "gatsby"
const ExampleComponent = ({data}) =>{
// Build Time Data Fetching
const takeshapeData = useStaticQuery(graphql`
query {
takeshape{
getProductList{
items{
_id
name
price
}
}
}
}`)
return (
<section>
<h1>Products:</h1>
<ul>
{
takeshapeData.takeshape.getProductList.items.map(
product=>(
<li key={product._id}>
{product.name}: {product.price}
</li>
)
)
}
</ul>
</section>
)
}
export default ExampleComponent
Making Queries with TakeShape's plugin
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 APIs and services, the TakeShape plugin will allow you to interface with those services with 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.
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.
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
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
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 need help? Get in touch with us.