Nonsense Placement Mandatory

    @openlab/vercel-netlify-cms-github
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.1 • Public • Published

    vercel-netlify-cms-github

    An NPM package to allow you to use netlify-cms with GitHub authentication when deploying on Vercel.

    Installation

    1. Install the module

    # cd into/your/vercel/project
    npm install @openlab/vercel-netlify-cms-github

    2. Create the auth route

    Create a vercel endpoint at api/auth.ts

    export { auth as default } from '@openlab/vercel-netlify-cms-github'

    3. Create the callback route

    Create a vercel endpoint at api/callback.ts

    export { callback as default } from '@openlab/vercel-netlify-cms-github'

    4. Update your config.yml

    Update your config.yml to include this backend

    backend:
      name: github
      repo: YOUR_GITHUB_REPO
      base_url: YOUR_WEBSITE
      auth_endpoint: api/auth
    • repo should be your GitHub repo path, like owner/repo
    • base_url should be the full url to the root of your site, like https://example.com/
    • auth_endpoint needs to be set to link it up correctly, you can't put it in base_url

    (optional) Configure vercel.json

    If you have your admin files in a folder (e.g. admin/index.html and admin/config.yml) you might want to force vercel to use trailing slashes. This is because if you visit /admin netlify will look for a config at /config.yml, not in the admin folder.

    To solve this add (or update) your vercel.json in the project root:

    {
      "trailingSlash": true
    }

    5. Commit these endpoints to git

    git add api/auth.ts api/callback.ts
    git commit -m ":star: add GitHub auth routes and connect to netlify-cms"

    6. Create a GitHub OAuth application

    Go to https://github.com/settings/developers.

    • Set Homepage URL to your site's homepage
    • Set Authorization callback URL to `https://YOUR_SITE_HERE/api/callback
    • Make a note of your client_id and client_secret

    7. Setup Vercel environment variables

    Go to your vercel dashboard, https://vercel.com.

    • Navigate to your project then Settings > Environment Variables
    • Add OAUTH_CLIENT_ID and set the value from the GitHub OAuth application
    • Add OAUTH_CLIENT_SECRET and set the value from the GitHub OAuth application
    • You can store them however you like but secrets should be the most secure
    • Make sure your environment variables are exposed on the deployment(s) you need

    Done

    🎉 Your site should now be linked up!

    Configuration

    Environment Variables

    In addition to OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, this package also exposes these variables to configure the GitHub authentication. These all have default values configured to talk to github.com.

    • OAUTH_HOST (default: https://github.com) The GitHub server to talk to
    • OAUTH_TOKEN_PATH (default: /login/oauth/access_token) The path of the GitHub OAuth token endpoint
    • OAUTH_AUTHORIZE_PATH (default: /login/oauth/authorize) The path of the GitHub OAuth Authorization endpoint

    API usage

    Other than the Vercel endpoints, these are exported:

    • oauthConfig is an object with configuration for simple-oauth2
    • randomState is a function to generate a random state for an OAuth2 flow
    • renderResponse is a function to generate HTML with client-side JavaScript to complete the OAuth2 flow using window.opener.postMessage

    These were primarily exposed for digitalinteraction/netlify-cms-github-auth to use.


    This project was set up by puggle

    Keywords

    none

    Install

    npm i @openlab/vercel-netlify-cms-github

    DownloadsWeekly Downloads

    65

    Version

    1.1.1

    License

    MIT

    Unpacked Size

    18.6 kB

    Total Files

    16

    Last publish

    Collaborators

    • robb_j
    • danielgjackson