drive-apig
v2.4.2

Cloudflare Pages (docs)

This site is a Next.js static export on Cloudflare Pages, served at https://docs.drive.com.au/drive-apig/* by a shared router Worker in drive-docs.

Architecture

flowchart LR
  GH[caradvice/drive-apig<br/>develop] -->|push| CFP[CF Pages build]
  CFP -->|next build + basePath shuffle| OUT[out/drive-apig/*]
  OUT --> ROUTER[drive-docs router Worker]
  USER[docs.drive.com.au/drive-apig/] --> ROUTER
  ROUTER --> OUT

docs/site/ is a standalone package (own package.json, yarn.lock, .yarnrc.yml) — not part of the apig yarn workspaces. Keeps Next 15/React 19 deps isolated; avoids pulling the whole monorepo into the CF build.

Terraform

platform/terraform/env-docs/main.cf-pages.tf:

  • Project: drive-apig-docs, production branch develop, GitHub app on caradvice/drive-apig.
  • Build: install + build inside docs/site, then move the export into a drive-apig/ subdir for DOCS_BASE_PATH=/drive-apig: 
    cd docs/site && yarn install --immutable && yarn build \
  && mv out _export && mkdir out && mv _export out/drive-apig \
  && mv out/drive-apig/_headers out/_headers \
  && printf '/ /drive-apig/ 302\n' > out/_redirects
  • Env vars: NODE_VERSION=22.22.0, DOCS_BASE_PATH=/drive-apig, DOCS_SITE_URL=https://docs.drive.com.au, GH_REGISTRY_TOKEN (SSM).

Separate stack from env-dev/staging/prod (those pin Cloudflare provider 3.x, which lacks cloudflare_pages_project).

basePath

Next.js basePath rewrites emitted hrefs but not filesystem layout. The build shuffle moves the flat export into drive-apig/ so absolute asset paths resolve on CF Pages. _redirects sends the pages.dev preview root to /drive-apig/.

Manual prerequisites (one-time)

Documented in main.cf-pages.tf header comment, not automated:

  1. Install CF Pages GitHub app on caradvice/drive-apig.
  2. Create CF API token (Pages: Edit + Zone DNS/Read on drive.com.au).
  3. Store in SSM: /shared/drive/ext/cloudflare/apig/api_token.
  4. Create TFC workspace drive-apig-docs (org drive-apig).
  5. Add drive-apig to allowed_repos in drive-docs/platform/terraform/env-shared.

Access gating

docs.drive.com.au/drive-apig/* and drive-apig-docs.pages.dev/* gated by Cloudflare Zero Trust apps owned by drive-docs/platform/terraform/env-shared.

Local dev

bash
cd docs/site
GH_REGISTRY_TOKEN="${GH_REGISTRY_TOKEN:-dummy}" yarn install
yarn dev      # http://localhost:3210 (no basePath)
yarn build    # static export to docs/site/out/
yarn preview  # serve the built out/ dir
Esc
Esc Close