NextJS

Getting started guide for using Pokko with NextJS websites

Pokko provides a GraphQL endpoint for querying content that integrates with any platform that can consume data coming from such an endpoint.

Using the content hierarchy feature of Pokko you can easily map content in Pokko to web pages on your website.

The website for Pokko - pokko.io - is a NextJS website with Typescript connected to Pokko. You can view the source code for the site here.

It's worth noting that the guide below isn't necessarily tied to NextJS, but could apply to any Javascript-based application.

Getting started

The simplest way to connect NextJS to Pokko is to add a thin API layer using the Apollo GraphQL client.

Start by adding the required dependencies.

yarn add @apollo/client graphql

# or, if you are using npm

npm install --save @apollo/client graphql

Then create a file somewhere in your project; we tend to use lib/pokko.ts in our projects.

import {
  ApolloClient,
  ApolloClientOptions,
  InMemoryCache,
  NormalizedCacheObject,
} from "@apollo/client";

const config = {
  environment: process.env.POK_ENVIRONMENT!,
  project: process.env.POK_PROJECT!,
  token: process.env.POK_TOKEN!,
};

const options = (
  token: string
): ApolloClientOptions<NormalizedCacheObject> => ({
  cache: new InMemoryCache(),

  headers: {
    "X-Token": token,
  },

  uri: `https://au-syd1.pokko.io/${config.project}/${config.environment}/graphql`,
});

export const client = new ApolloClient(options(config.token));

This expects the environment variables for POK_ENVIRONMENT , POK_PROJECT and POK_TOKEN. These can go into your .env file.

aWith that, you can query content using the client export from this file, it will provide you with a raw GraphQL interface to query content.

Code generation

We like to use a library called GraphQL Codegen that allows us to write GraphQL queries and store them in .graphql files that are then validated against the Pokko API and then output into Typescript files for easier consumption.

It only takes a few moments to configure but will save you tonnes of time in the long run.

Start by installing the dependencies.

yarn add --dev @graphql-codegen/cli @graphql-codegen/fragment-matcher @graphql-codegen/typescript @graphql-codegen/typescript-apollo-client-helpers @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo

# or, with npm

npm install --save-dev @graphql-codegen/cli @graphql-codegen/fragment-matcher @graphql-codegen/typescript @graphql-codegen/typescript-apollo-client-helpers @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo

Then create a codegen.yml file alongside your package.json with the contents below. You can put these files wherever you like, this is just how we set things up.

schema:
  - https://au-syd1.pokko.io/<< PROJECT ID >>/<< ENVIRONMENT ID >>/graphql:
      headers:
        X-Token: ${POK_TOKEN}
documents:
  - pokko/queries/*.graphql
generates:
  ./pokko/queries.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
      - fragment-matcher

The URL on line 2 can be found by following the steps here, the URL for the "GraphQL Playground" is what will go here.

This will look for .graphql files in the pokko/queries folder and output the generated Typescript to pokko/queries.ts

This also looks for your API key in your environment variables, you can create a .env file with POK_TOKEN=<< API TOKEN >> alongside the codegen.yml file.

With this in place, you can run yarn run graphql-codegen to generate the Typescript file.

There is one extra piece needed if you use data model inheritance, that is to update your lib/pokko.ts file to the following.

import {
  ApolloClient,
  ApolloClientOptions,
  InMemoryCache,
  NormalizedCacheObject,
} from "@apollo/client";
import intro from "../pokko/queries"; // <-- add this

const config = {
  environment: process.env.POK_ENVIRONMENT!,
  project: process.env.POK_PROJECT!,
  token: process.env.POK_TOKEN!,
};

const options = (
  token: string
): ApolloClientOptions<NormalizedCacheObject> => ({
  cache: new InMemoryCache({
    possibleTypes: intro.possibleTypes,  // <-- and this
  }),

  headers: {
    "X-Token": token,
  },

  uri: `https://au-syd1.pokko.io/${config.project}/${config.environment}/graphql`,
});

export const client = new ApolloClient(options(config.token));