# NextJS

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](/advanced-features/content-hierarchy.md) feature of Pokko you can easily map content in Pokko to web pages on your website.

The website for Pokko - [pokko.io](https://www.pokko.io/) - is a NextJS website with Typescript connected to Pokko.  You can view the source code for [the site here](https://github.com/pokkocms/website).

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](https://www.graphql-code-generator.com/) 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](/basic-features/getting-started.md#api-keys), 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));
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pokko.io/guides/nextjs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.