next-tinacms-github

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

npm install --save next-tinacms-github

or

yarn add next-tinacms-github

Getting Started

Any functions in the pages/api directory are are mapped to /api/* endpoints.

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 accesible through getStaticProps throughout your app.

//Blog template [slug].ts

import {
  getMarkdownFile as getGithubMarkdownFile,
} from 'next-tinacms-github'

// ...

export const getStaticProps: GetStaticProps = async function({
  preview,
  previewData,
  ...ctx
}) {
  const { slug } = ctx.params

  let file = {}
  const filePath = `content/blog/${slug}.md`

  const sourceProviderConnection = {
    forkFullName: previewData.fork_full_name,
    headBranch: previewData.head_branch || 'master', 
  }
  
  let error = null

  if(preview) {
    try {
    file = await getGithubMarkdownFile(filePath,
      sourceProviderConnection, 
      previewData.accessToken)
    }
    catch (e) {
      // If there is an error initially loading the content from Github, we want to display an actionable error
      // to the user. They may need to re-authenticate or create a new fork.
      if (e instanceof GithubError) {
        error = { ...e } //workaround since we cant return error as JSON
      } else {
        throw e
      }
    }
  }
  else {
    // Get your production content here
    // when you are not in edit-mode
     file = await readLocalMarkdownFile(filePath)
  }

  return {
    props: {
      sourceProviderConnection,
      editMode: !!preview,
      file,
      error
    },
  }
}

Github Oauth App:

In GitHub, within your account Settings, click Oauth Apps under Developer Settings.

click "New Oauth App".

For the Authorization callback URL, enter the url for the "authorizing" page that you created above (e.g https://your-url/github/authorizing). Fill out the other fields with your custom values. Note: If you are testing your app locally, you may need a separate development Github app (with a localhost redirect), and a production Github app.

The generated Client ID & Client Secret will be consumed by the createCreateAccessTokenFn defined above.

Next steps

Now that we have configured our backend API functions to manage our Github authentication token, we will need to configure the front-end to use these endpoints. You may want to use the next-tinacms-github package.