next-tinacms-github

This package provides helpers for managing the GitHub auth token for requests, as well as providing helpers for loading content from the Github API.

Installation

yarn add next-tinacms-github

Any functions in the pages/api directory are are mapped to /api/* endpoints. The below helpers tend to be added to the pages/api directory in a Next.js project.

createCreateAccessTokenFn

Helper for creating a createCreateAccessToken server function.

pages/api/create-github-access-token.ts

import { createAuthHandler } from 'next-tinacms-github'

export default createAuthHandler(
  process.env.GITHUB_CLIENT_ID,
  process.env.GITHUB_CLIENT_SECRET
)

See Next's documentation for adding environment variables

See below for instructions on creating a Github OAuth App to generate these Client ID & Client Secret variables.

apiProxy

Proxies requests to GitHub, attaching the GitHub access token in the process.

pages/api/proxy-github.ts

import { apiProxy } from 'next-tinacms-github'

export default apiProxy

previewHandler

Handles setting the the Nextjs preview data from your cookie data.

pages/api/preview.ts

import { previewHandler } from 'next-tinacms-github'

export default previewHandler

Loading content from Github

The preview data, which gets set by calling your preview function, will be accessible through getStaticProps throughout your app.

Below is an example of the conditional data fetching, from the local environment or Working GitHub Repository based on the preview environment:

/blog/slug.ts

import {
  getGithubPreviewProps
  parseMarkdown,
} from 'next-tinacms-github'

// ...

export const getStaticProps: GetStaticProps = async function({
  preview,
  previewData,
  ...ctx
}) {
  if (preview) {
    return getGithubPreviewProps({
      ...previewData,
      fileRelativePath: 'src/content/home.json',
      parse: parseMarkdown
    });
  }
  return {
    props: {
      sourceProvider: null,
      error: null,
      preview,
      file: {
        fileRelativePath: 'src/content/home.json',
        data: (await import('../content/home.json')).default,
      },
    },
  };
}

getGithubPreviewProps

The getGithubPreviewProps function accepts this preview data:

interface PreviewData<Data> {
  github_access_token: string
  working_repo_full_name: string
  head_branch: string
  fileRelativePath: string
  parse(content: string): Data
}

It then fetches the content from the Working GitHub Repository and returns a props object with this shape:

return {
  props: {
    file,
    repoFullName: workingRepoFullName,
    branch: headBranch,
    preview: true,
    error,
  },
}

Parsing Data

next-tinacms-github provides two content parsing options available, for Markdown — parseMarkdown or JSON — parseJson. Or you could pass in a custom parser.