Integrating Prismic's GraphQL API with an existing Javascript Project

If you already have a Javascript project that you want to integrate with Prismic, then you can simply add the Apollo Client and Prismic Apollo Link as dependencies to your project. Let's walk through all the steps to get Prismic integrated into your project!

1. Create a content repository

A content repository is where you define, edit, and publish content.

Create a new repository

Next you'll need to model your content, create your custom types, and publish some documents to your repository. To learn more, check out our documentation for Creating Custom Types.

Now, let's take a look at how to connect this new content with your project.

Let's add the Prismic development kits as dependencies to your project. Launch the terminal (command prompt or similar on Windows), point it to your project location, and run the following command.

Copy
npm install apollo-client apollo-cache-inmemory graphql-tag graphql apollo-link-prismic --save

3. Connect to the API and query your content

Next we need to connect to your Prismic API in order to retrieve your content.  

First we will define the Apollo Link to help you query your API.

  • react
  • nodejs
Copy
import { PrismicLink } from "apollo-link-prismic";
import { InMemoryCache } from "apollo-cache-inmemory";
import ApolloClient from "apollo-client";
import gql from "graphql-tag";

const client = new ApolloClient({
  link: PrismicLink({
    uri: "https://your-repository-name.prismic.io/graphql",
  }),
  cache: new InMemoryCache()
});
Copy
var InMemoryCache = require("apollo-cache-inmemory").InMemoryCache;
var ApolloClient = require("apollo-client").ApolloClient;
var gql = require("graphql-tag");
var PrismicLink = require("apollo-link-prismic").PrismicLink;
const client = new ApolloClient({
  link: PrismicLink({
    uri: "https://your-repository-name.prismic.io/graphql"
  }),
  cache: new InMemoryCache()
});

If you are using a private API, then you'll need to include your access token like this.

  • react
  • nodejs
Copy
const client = new ApolloClient({
  link: PrismicLink({
    uri: "https://your-repository-name.prismic.io/graphql",
    accessToken: "YOUR ACCESS TOKEN IF YOUR API IS PRIVATE"
  }),
  cache: new InMemoryCache()
});
Copy
const client = new ApolloClient({
  link: PrismicLink({
    uri: "https://your-repository-name.prismic.io/graphql",
    accessToken: "YOUR ACCESS TOKEN IF YOUR API IS PRIVATE"
  }),
  cache: new InMemoryCache()
});

3.2 Query your content

You'll then be able to use the gql tag to perform your query.

  • react
  • nodejs
Copy
client.query({
  query: gql`
    ...your GraphQL query goes here...
  `
}).then(response => {
  console.log(response);
}).catch(error => {
  console.error(error);
});
Copy
app.get('/website-url', function(req, res) {
  client.query({
    query: gql`
      ...your GraphQL query goes here...
    `
  }).then(response => {
    console.log(response);
  }).catch(error => {
    console.error(error);
  });
});

Test your queries in the GraphQL API Explorer

You can test your queries in the GraphQL Explorer at https://your-repo.prismic.io/graphql

Here is a simple example that will query the "title" field for the blog that has the UID value of "prismic". The response will then be displayed in the developer console.

  • react
  • nodejs
Copy
client.query({
  query: gql`
    query{
      blog(lang:"en-us",uid:"prismic"){
        title
      }
    }
  `
}).then(response => {
  console.log(response);
}).catch(error => {
  console.error(error);
});
Copy
app.get('/website-url', function(req, res) {
  client.query({
    query: gql`
      query{
        blog(lang:"en-us",uid:"prismic"){
          title
        }
      }
    `
  }).then(response => {
    console.log(response);
  }).catch(error => {
    console.error(error);
  });
});

Pagination of API Results

When querying a Prismic repository, your results will be paginated. The GraphQL API will return a maximum of 20 documents per page. You can read more about how to manipulate the pagination in the Paginate your results page.

Next, we will define a link resolver which will determine what a page's url will look like. This will be used for the preview functionality as well as when we add our content to the templates.

You can read more about this on our Link Resolving for Javascript page.

You will need to modify the link resolver to fit your needs. Here is a simple example:

Copy
// Link Resolver
function linkResolver(doc) {
  
  // Define the url depending on the document type
  if (doc.type === 'page') {
    return '/page/' + doc.uid;
  } else if (doc.type === 'blog_post') {
    return '/blog/' + doc.uid;
  }
  
  // Default to homepage
  return '/';
}

5. Add the queried content to your templates

Once you've retrieved your content, you can include it in your template. In order to display certain fields such as Rich Text, you will need to use the helper functions included in one of our helper libraries such as prismic-dom, prismic-reactjs, or prismic-vue. Refer to the templating documentation for your particular technology or framework to learn which library to use.

And your Prismic journey begins!

You should have all the tools now to really dig into your project. We invite you to further explore the docs to learn how to define your Custom Types, create advanced queries, and add your content to your templates.