astro-decap-cms-oauth

Astro integration for the Decap CMS with custom OAuth backend

This integration automatically mounts the Decap CMS admin dashboard to /admin and custom OAuth authentication backend routes to /oauth, /oauth/callback using GitHub as the provider.

This way, you aren't vendor-locked to Netlify and your app can be deployed anywhere that supports SSR.

Installation

npx astro add astro-decap-cms-oauth

Manual Installation

npm install astro-decap-cms-oauth

Add the integration and set output to server or hybrid in your astro.config.mjs file:

import { defineConfig } from "astro/config";
import decapCmsOauth from "astro-decap-cms-oauth";

export default defineConfig({
    ...,
    integrations: [decapCmsOauth()],
    output: "server",
});

Usage

1. Make sure Astro is in SSR mode (output: "server" set in astro.config.mjs)

2. Put your config.yml file in public/admin/config.yml (see Decap CMS Docs for more info)

backend:
  name: github
  branch: main # change this to your branch
  repo: dorukgezici/astro-decap-cms-oauth # change this to your repo
  site_domain: astro-decap-cms-oauth.vercel.app # change this to your domain
  base_url: https://astro-decap-cms-oauth.vercel.app # change this to your prod URL
  auth_endpoint: oauth # the oauth route provided by the integration

3. Set up GitHub

You can either use a GitHub OAuth app or a Github app to get set up.

GitHub OAuth

On GitHub, go to Settings > Developer Settings > OAuth apps > New OAuth app. Or use this direct link.

Homepage URL: This must be the prod URL of your application.

Authorization callback URL: This must be the prod URL of your application followed by /oauth/callback.

GitHub App

Register a new GitHub application on GitHub (details).

Select the scopes as content:write

Homepage URL: This must be the prod URL of your application.

Authorization callback URL: This must be the prod URL of your application followed by /oauth/callback.

Once registered, click on the Generate a new client secret button. The app’s Client ID and Client Secret will be displayed.

Then navigate to https://github.com/apps/<app slug>/installations/new to install it on the repo. You can scope the access tokens further if wanted - details on this page

curl -s 'https://api.github.com/repos/<owner>/<repo>' | jq .id

You can then use this ID for the OAUTH_GITHUB_REPO_ID environment variable.

4. Set env variables

# GitHub OAuth App & GitHub App
OAUTH_GITHUB_CLIENT_ID=
OAUTH_GITHUB_CLIENT_SECRET=
# GitHub App only
OAUTH_GITHUB_REPO_ID=
# optional
PUBLIC_DECAP_CMS_SRC_URL=https://unpkg.com/decap-cms@^3.3.3/dist/decap-cms.js
PUBLIC_DECAP_CMS_VERSION=3.3.3

Configuration Options

export interface DecapCMSOptions {
  decapCMSSrcUrl?: string;
  decapCMSVersion?: string;
  adminDisabled?: boolean;
  adminRoute?: string;
  oauthDisabled?: boolean;
  oauthLoginRoute?: string;
  oauthCallbackRoute?: string;
}

const defaultOptions: DecapCMSOptions = {
  decapCMSSrcUrl: "",
  decapCMSVersion: "3.3.3",
  adminDisabled: false,
  adminRoute: "/admin",
  oauthDisabled: false,
  oauthLoginRoute: "/oauth",
  oauthCallbackRoute: "/oauth/callback",
};

To override default version of Decap CMS used, set PUBLIC_DECAP_CMS_VERSION env variable (takes precedence) or decapCMSVersion in astro.config.mjs. To override the full js source, set PUBLIC_DECAP_CMS_SRC_URL env variable (takes precedence) or decapCMSSrcUrl in astro.config.mjs. If set, PUBLIC_DECAP_CMS_VERSION is ignored. To disable injecting Decap CMS admin route, set adminDisabled to true in astro.config.mjs. To disable injecting OAuth routes, set oauthDisabled to true in astro.config.mjs.

import { defineConfig } from "astro/config";
import decapCmsOauth from "astro-decap-cms-oauth";

export default defineConfig({
    ...,
    integrations: [decapCmsOauth({ decapCMSVersion: "3.3.3", adminDisabled: false, oauthDisabled: true })],
    output: "server",
});