ops-run-local_skill

Overview

This skill manages the local development environment for Expo frontend and a serverless backend. It provides start, stop, restart, and status controls for the full stack or individual services with sensible defaults and health checks. It targets projects using bun and Serverless Offline conventions and expects the backend in ../backend-v2 unless configured otherwise.

How this skill works

The skill inspects the frontend and backend package.json to pick appropriate start scripts and uses environment variables to locate the backend directory. It runs backend and frontend processes in the background, waits for HTTP health checks (GraphQL and Metro bundler) to confirm readiness, and exposes commands to stop or report status of running services. It also performs port checks, bun verification, and optional Docker shutdown for backend compose stacks.

When to use it

• Start the full local stack for development and mobile testing (frontend + serverless backend).
• Run only the frontend locally while pointing to a deployed backend (start-frontend).
• Run only the backend locally to develop serverless functions and GraphQL APIs (start-backend).
• Quickly stop all local services and Docker compose for a clean environment.
• Check which services are listening and responsive before debugging or CI tasks.

Best practices

• Set BACKEND_DIR in .claude/settings.local.json if your backend is not at ../backend-v2.
• Verify bun is installed and on PATH before starting services.
• Ensure ports 8081 (Metro) and 3000 (Serverless Offline) are free to avoid collisions.
• Use the package.json start scripts (start:local, start:dev) so the skill can discover commands.
• Check AWS credentials before starting backend if scripts require aws:signin for local secrets.

Example use cases

• Local full-stack development: run start to launch backend in background, wait for GraphQL, then start Metro bundler and verify both services.
• Frontend-only testing: run start-frontend to launch Metro locally while using a remote backend endpoint.
• Backend function development: run start-backend to bring up serverless offline, verify GraphQL responds, and iterate on handlers.
• Clean shutdown: run stop to kill processes on ports 8081 and 3000 and bring down Docker compose for the backend.
• Automated restart in CI or dev scripts: run restart to stop, wait briefly, then relaunch services with health checks.