aptlylabs-ui

Hosting the docs at ui.aptlylabs.com (GitHub Pages)

The Vite app in apps/docs is a static SPA (react-router-dom). Deploy apps/docs/dist with GitHub Actions (see .github/workflows/deploy-docs.yml).

SPA routing on GitHub Pages

GitHub Pages does not rewrite all URLs to index.html. For unknown paths it serves 404.html. The docs build copies index.html → 404.html after vite build (apps/docs/scripts/gh-pages-spa.mjs) so deep links like /blocks/… load the app after refresh.

Custom domain

• apps/docs/public/CNAME contains ui.aptlylabs.com and is copied into dist/ at build time.
• In the repo: Settings → Pages → Custom domain → ui.aptlylabs.com, then add the DNS records GitHub shows (usually a CNAME for ui → <user>.github.io or the target from the Pages UI).

Enable deployment

1. Settings → Pages → Build and deployment → Source: GitHub Actions (not “Deploy from a branch” for this workflow).
2. Under Custom domain, enter ui.aptlylabs.com and save so GitHub binds that hostname to this repository’s Pages deployment (DNS alone is not enough).
3. Push to main (or run Actions → Deploy docs manually). The workflow runs npm ci and npm run build -w @aptlylabs/docs, then publishes apps/docs/dist (it uses actions/configure-pages before upload so the artifact is tied to Pages).
4. Node: the workflow uses Node 20; .nvmrc at the repo root matches for local installs.

“There isn’t a GitHub Pages site here” at the custom domain

Usually either no successful deploy yet (check Actions) or the custom domain is not saved on this repo’s Settings → Pages. Confirm the latest Deploy docs run finished green; after fixing the workflow, Re-run all jobs or push an empty commit to redeploy.

Local check

npm ci
npm run build -w @aptlylabs/docs
ls apps/docs/dist/404.html   # should exist (copy of index.html)
cd apps/docs && npm run preview

Open a deep link such as /blocks/dashboard-shell and confirm it loads after refresh.