Prevent 404 Downtime Deploying Docusaurus with GitHub Actions

by

Summary

When deploying a Docusaurus site with GitHub Actions, the production URL can serve 404 responses for several minutes while the build runs. This latency is not typical for other static site generators and can be avoided with proper build practices.

Root Cause

  • Monolithic build: docusaurus build takes ~3 min to compile all pages and resources.
  • Immediate swap: The new artifact replaces the old one only after the whole bundle is ready.
  • Consecutive deployments: If a new push occurs mid‑build, the previous deployment is still held until the new one completes.

Why This Happens in Real Systems

  • Static sites often use pre‑generated snapshots; the server can still serve the old snapshot while the new one is ready.
  • Docusaurus, by default, writes the entire output, not incrementally.
  • GitHub Actions deploys to a fresh runner each time, so the old files are removed before upload.

Real-World Impact

  • Downtime: Users see 404 pages, resulting in a poor experience.
  • SEO penalty: Frequent 404s can negatively affect search rankings.
  • Developer frustration: Re‑triggers of deployments can compound the issue.

Example or Code

# Example of a minimal GitHub Actions workflow for Docusaurus
name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install deps
        run: npm ci
      - name: Build
        run: npm run docusaurus build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          publish_dir: ./build

How Senior Engineers Fix It

  • Incremental builds: Use docusaurus build --no-clean to reuse existing files and reduce runtime.
  • Prerender caching: Store the previous build directory as a cache between runs.
  • Staged deployment: Push the new bundle to a staging branch first, test, then promote.
  • Atomic uploads: Deploy to a temporary bucket or path, then move to the final path in one step.
  • Parallel jobs: Separate build and deploy jobs to allow overlap and faster switching.

Why Juniors Miss It

  • Newer engineers often assume the entire static build is always visible; they overlook the fact that the host serves only the final artifact.
  • They may not be aware of incremental build options or how caching can keep the old release live until the new one is ready.
  • Without monitoring latency, the 404 issue goes unnoticed until users report it.

Leave a Comment