Skip to main content

Getting started

TakeShape is a great way to add the power of a GraphQL API to your 11ty project without having to build one out manually yourself. Just create a project with the TakeShape web client, connect the API services you need, customize your schema, and you're all set!

This doc will walk you through that entire process. The first step is connecting 11ty to your TakeShape project.

Connecting a project#

Integrating TakeShape's API Mesh with 11ty requires a project ID and an API Key. But you won't have either of those things if you don't have a project!

If you haven't created a project yet, you can do that by following our docs on creating new projects.

Read our docs on creating an API Key here.

To find your Project ID, go to your TakeShape project in your web browser. The Project ID can be found in the lower left of the dashboard.

Adding your API Key and Project ID to your config#

Configuration files are optional in 11ty projects, but you'll need one in order to integrate TakeShape. To do so safely, you'll need to create a .env file, which will hide your API Key and Project ID from public access.

At the root of your project, create a file called .env. Now inside this file, create environment variables and set them to your API Key and Project ID. For example:

.env
API_KEY=1234-5678
PROJECT_ID=abcd-efg

To access these variables, you will need to use the dotenv npm package. Learn how to do so below. Or skip ahead to adding TakeShape to your build process

Installing and implementing dotenv#

Run npm install dotenv in your command line.

In the root directory of your project folder, create a file called .eleventy.js. Learn more about setting this file up with the 11ty config docs!

On the first line of the file, add:

.eleventy.js
require('dotenv').config();

Now, if you want to import any environment variables into your build scripts, you can use Node's process.env object. Learn more in the Node docs.

Adding TakeShape to your build process#

11ty uses JavaScript Data Files to give your templates access to data that is computed or obtained at build time. Read the 11ty docs on data files to learn more about scoping data to specific templates. In this project, we'll be working with a global data file that will available to all of your templates.

To create a global data file, in the root of your project directory you must create a folder called _data. In this directory, you will create a JS module, which you can name whatever you like. For this example we want to simulate pulling a set of generic items into your project via TakeShape, we we'll call our module items.js.

Info

You can name the _data folder anything you want, but you have to define the custom name of the folder in your .eleventy.js config. Read the 11ty docs for more information.

To pull data from TakeShape, you'll use a fetch request. You'll need to install the node-fetch npm package, because JavaScript's fetch functionality is not included in Node by default.

With that done, let's start editing our items.js file!

items.js
const fetch = require('node-fetch');
//Retrieve our TakeShape data from our .env file
const key = process.env.API_KEY;
const projectId = process.env.PROJECT_ID;
//Create our API endpoint from a string template.
const takeshape = `https://api.takeshape.io/project/${projectId}/graphql`;

The above code simply imports the fetch npm package, then defines our API endpoint as a string template containing the Project ID we saved in our local .env file.

Next, define the function that the module will export. Because you'll be interfacing with your project's GraphQL API, this code will be highly dependent on your project's schema.

Check out our docs on configuring your project's schema to learn more.

The below code will show you an example of what your code might look like. You can use it as a starting point for building your own code. It demonstrates interfacing with your project's API through a fetch request, and returning the data you receive.

First, we make a fetch request with the authorization header set to Bearer ${key}. Next, we specify the GraphQL query we want to make in the body of our request.

Read our doc on calling the GraphQL API to learn more.

The important property on the body object will be called query. This property will contain a string with your GraphQL query.

items.js
const fetch = require('node-fetch');
const key = process.env.API_KEY;
const projectId = process.env.PROJECT_ID;
const takeshape = `https://api.takeshape.io/project/${projectId}/graphql`;
module.exports = async () => {
//takeshape is the endpoint defined
const getItemList = await fetch(takeshape, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
Authorization: `Bearer ${key}`,
},
body: JSON.stringify({
query: `
{
getItemList {
items {
name
age
}
}
}
`,
}),
});
const response = await getItemList.json();
return response.data.getItemList.items;
};

The above query is an example; our query will be based on the queries and mutations you have defined in your project's schema. If you'd like to test out different queries without having to run a dev server, check out the API Explorer feature on the TakeShape web client.

To access the data pulled from TakeShape with your project module, just insert the below code at the top of your page template:

items.js
---
layout: your_layout_here
data: items
---

Further Reading#

You're all set up! For a more in-depth example of using TakeShape with 11ty, check out this amazing post on our blog!

Still confused? Ask for help!. We'd love to solve your problem.