antigravity-skills-reference/apps/web-app/README.md

Antigravity Web App

This app is the static catalog and skill browser for antigravity-awesome-skills. It ships the generated registry, renders searchable skill detail pages, and publishes the public site to GitHub Pages.

What This App Does

• Loads the generated skill catalog and related metadata from tracked assets in public/.
• Renders home, category, bundle, and skill detail routes for the published library.
• Adds SEO metadata, sitemap-backed URLs, and static asset resolution for GitHub Pages.
• Supports a local-only "refresh skills" developer flow through the Vite dev server plugin.

Architecture

• src/pages/ contains top-level route screens such as Home.tsx and SkillDetail.tsx.
• src/context/ holds catalog loading and shared app state.
• src/hooks/ contains feature-specific client hooks such as star state and filters.
• src/utils/ contains URL, SEO, and content helpers.
• public/ contains generated catalog artifacts copied from the repo root as part of maintainer sync flows.

The app intentionally assumes a static hosting model in production. Anything that depends on /api/* is development-only unless it is backed by a real serverless or backend implementation.

Development

From the repo root:

npm run app:install
npm run app:dev

Or directly from this directory:

npm ci
npm run dev

Useful root-level commands:

npm run app:build
npm run sync:web-assets

Environment Variables

The app reads configuration from .env files in apps/web-app/.

• VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY: optional read access for read-only community save counts.
• VITE_ENABLE_SKILLS_SYNC=true: explicitly exposes the local maintainer-only sync button during development.
• VITE_SYNC_SKILLS_TOKEN: local development token accepted by the Vite refresh plugin.
• VITE_SITE_URL: optional override for canonical URL generation when testing non-default hosts.

Saving a skill is intentionally browser-local for now. The UI should not imply a shared write path until the project has a real backend contract for persistence, abuse controls, and deployment.

Deploy Model

Production deploys use GitHub Pages and publish the built dist/ output from this app. That means:

• production is static
• Vite configureServer hooks are not available in production
• any refresh or sync endpoint exposed by a dev plugin must be hidden or replaced by a real backend before being treated as a public feature

Maintainers should treat public/skills.json.backup, public/sitemap.xml, and other generated assets as derived artifacts synced from the repo root during release and hygiene workflows.

Catalog Data Flow

The high-level maintainer flow is:

1. update skill sources under skills/
2. regenerate canonical registry artifacts from the repo root
3. sync tracked web assets into apps/web-app/public/
4. build this app for Pages

npm run sync:repo-state and npm run sync:release-state are the safest entrypoints because they keep the root catalog and the web assets aligned.

Testing

From the repo root:

cd apps/web-app && npm run test
cd apps/web-app && npm run test:coverage
npm run test

The repo-level test suite also contains workflow and documentation guardrails outside src/, so changes to this app can fail tests in tools/scripts/tests/ even when the React code itself is untouched.

Troubleshooting

• If the app shows stale catalog data, run npm run sync:web-assets from the repo root and rebuild.
• If a feature works in npm run app:dev but not on GitHub Pages, check whether it depends on a dev-only Vite plugin or non-static runtime behavior.
• If canonical URLs or asset links look wrong, inspect the shared path/base URL helpers before patching individual pages.