@openlab/vercel-netlify-cms-github
v1.1.1
Published
Vercel API routes to login to netlify-cms deployed on vercel
Downloads
333
Readme
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
andclient_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 toOAUTH_TOKEN_PATH
(default:/login/oauth/access_token
) The path of the GitHub OAuth token endpointOAUTH_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-oauth2randomState
is a function to generate a random state for an OAuth2 flowrenderResponse
is a function to generate HTML with client-side JavaScript to complete the OAuth2 flow usingwindow.opener.postMessage
These were primarily exposed for digitalinteraction/netlify-cms-github-auth to use.
This project was set up by puggle