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 API Endpoint and an API Key. But you won't have either of those things if you don't have a 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.

Creating an 11ty project

Follow Along

Follow along with this guide by checking out our starter project repo. Our starters let you instantly deploy a pre-configured TakeShape project.

Otherwise, you can use one of 11ty's starter projects.

Our own TakeShaper 11 Starter is based on 11ty's base blog starter, which you can find here.

Whether you use a starter or not, you can install 11ty with the following command:

npm install -g @11ty/eleventy

Now navigate to the directory where you'd like your 11ty project to be. Use the following command to create your package.json:

npm init -y

Now you can create your own template files in any of 11ty's supported languages. Here's the full list. When you have your templates made, use the following command:

npx @11ty/eleventy --serve

We highly recommend you use either the TakeShape starter or one of the 11ty starters, though.

Adding your API Key and API Endpoint to your config

Configuration files are optional in 11ty projects, but you'll need one to integrate TakeShape. To do so safely, you'll need to create a .env file, which will hide your API Key and API Endpoint 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 API Endpoint. For example:

.env

API_KEY=1234-5678
API_ENDPOINT=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 products from an ecommerce backend into your project via TakeShape.

We'll call our module products.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.

npm i node-fetch

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

products.js
const fetch = require('node-fetch');

    //Retrieve our TakeShape data from our .env file
const key = process.env.API_KEY;
const endpoint = process.env.API_ENDPOINT;

The above code imports the fetch npm package, then defines our API endpoint as a string template containing the API Endpoint 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.

products.js
const fetch = require('node-fetch');
const key = process.env.API_KEY;
const endpoint = process.env.API_ENDPOINT;

module.exports = async () => {
    //takeshape is the endpoint defined
  const response = await fetch('YOUR-ENDPOINT-HERE', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json',
      Authorization: `Bearer YOUR-API-KEY-HERE`,
    },
    body: JSON.stringify({
      query: `query{
        getProductList{
          items{
            name
            price
          }
        }
      }`})
    });
  const responseJSON = await response.json();
  return responseJSON.data.getProductList.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:

index.njk
---
data: products
---

Here's an example of what your whole template could look like:

index.njk
---
data: products
---

<h1>Products</h1>
<ul>
    {% for product in products %}
      <li>
        {{product.name}}: {{product.price}}
      </li>
    {% endfor %}
</ul>

And here's what the final page might look like:

Getting started

Connecting a project​

Creating an 11ty project​

Adding your API Key and API Endpoint to your config​

Installing and implementing dotenv​

Adding TakeShape to your build process​

Further Reading​

Connecting a project

Creating an 11ty project

Adding your API Key and API Endpoint to your config

Installing and implementing dotenv

Adding TakeShape to your build process

Further Reading