How to setup Astro + Keystatic in a Dual-Deploy on Github Pages (Static) and Netlify (CMS)

[tordans]

I just rolled out a setup that works well to deploy a Astro + Keystatic Site on Github Pages and Netlify while still having a normal development setup.

This is my documentation of what we use at @FixMyBerlin and @osmberlin.

Goal

• Public page on Github Pages: Build the astro page as a static page (no hybrid, no server), so that things like Astro Redirects work as expected (they behave differently based on the output mode.
• CMS on Netlify: We use Netlify as our dynamic CMS in this setup, so we only really use the /keystatic route here and maybe the branch deployments for previews.
• Local: A normal local dev experience

In our setup, we use IONOS Deploy Now instead of Github Pages to serve a static site to our users from a GDPR friendly server. But the general setup is the same for Github pages and IONOS.

Repositories

You can find this full setup on those pages

• Using IONOS https://github.com/FixMyBerlin/nudafa/
• Using Github Pages https://github.com/osmberlin/www.osm-verkehrswende.org

General setup

We use environment variables to change the way Astro and Keystatic work during build and while running.
The trick is, to get the environment variables setup right …

Variables

For local development, copy https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/.env.example.local to your .env
You will modify it again after authenticating Keystatic with Github.

For GitHub Pages, the variables need to be put into the deploy workflow. You can use https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/.env.example.githubpages as a reference to update your Workflow like so https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/.github/workflows/deploy.yml#L26-L29

For Netlify, the variables need to be added to the Netlify Page Settings. Use https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/.env.example.netlify as a reference. We will copy the secrets from .env after setting this up locally.

Configuration

Astro config

We need to change how Astro builds based on our environment variables.

The trick here is, that we cannot use env variables in this file in the way we are used to in Astro. Instead we have to manually read the .env file like https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/astro.config.mjs#L12-L25

• We want to add the keystatic() integration to the config only when the Astro output mode is hybrid or server. We do this in https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/astro.config.mjs#L32 by looking at our ASTRO_OUTPUT_MODE env variable.
• We use the same variables to change the Astro output mode for each of the three environments https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/astro.config.mjs#L43-L47
• To build Astro on Netlify, we need the adapter: netlify(). But we do not wan this on Github pages or locally, so this is conditional as well: https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/astro.config.mjs#L43-L47

Keystatic config

We want to use github mode on Netlify, but local mode during dev.

However, for this config, we need to access the env variable in a way that makes it accessible on the client.
We use the new Astro Env API to define the variable in the astro config https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/keystatic.config.ts#L9-L10 which means we can access it easily in https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/keystatic.config.ts#L9-L10.
It also means, the build will fail when the variables are missing, which gives us clarity that everything is set up right.

Local build

The last thing is to be able to test the build locally. For this we overwrite the Astro output mode env variable just for the build and start command in https://github.com/osmberlin/www.osm-verkehrswende.org/blob/main/package.json#L9-L10 which allows us to test the Setup that will be used on Github pages locally with npm run build:local.

Usage

• Our primary domain serves the fully static astro page
• We use the Netlify URL to access /keystatic in Github mode

One gotcha is, that you will likely need to add the URL that Netlify generates to your Keystatic app. See https://github.com/Thinkmill/keystatic/pull/1359/files for how to find it on Github.