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.
If you haven't created a project yet, you can follow our guide to do that now.
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!
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.
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:
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.
Your Gatsby configuration file is a JS module that exports an object containing your configuration properties. Your file should contain:
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.
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.
Let's configure environment variables to avoid security issues. Install dotenv.
Now on the first line of your gatsby-config file, add this:
Create and open a .env file in the root of your project, then add the below code:
Now you'll be able to import these details into your gatsby-config file safely.
Make sure .env is included in your .gitignore so you don't accidentally commit your API key and Project ID!
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).
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.
|Your API Key from your project. You'll need |
|Your project ID from your TakeShape project. Click here to learn more.|
|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: |
|Additional options to pass in with the second argument to |
|Advanced. Override or set options passed to Dataloader. Dataloader is used if batch is true.|
|Throttle queries based on the |
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 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.
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.
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.
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.
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.
The TakeShape Gatsby plugin must be run from within a Gatsby project.
Still confused? Ask for help!