openresto: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Run everything (recommended for local dev)

npm run dev          # starts backend (dotnet watch) + frontend (expo) concurrently
npm run dev:native   # the same stack, addressed so a phone running Expo Go can reach it
npm test             # the root dev scripts' own tests (node --test, no jest at this level)

Both pass --kill-others --kill-timeout to concurrently, so one half dying takes the other down instead of leaving the backend squatting on :8080 where the next dotnet watch cannot bind. concurrently kills through tree-kill, which is what reaches the dotnet watch → dotnet run → OpenRestoApi grandchild that actually holds the port.

dev:native exists because openresto-frontend/.env points the app at http://localhost:8080, and in Expo Go localhost is the phone, so the app resolves it to itself and reaches no API at all. scripts/dev-native.mjs resolves this machine's LAN address and passes it as EXPO_PUBLIC_API_URL, which Metro bakes into the bundle at build time; @expo/env skips any key already in the system environment, so that wins over the .env file rather than racing it. Docker and podman bridges are filtered out deliberately — bring the compose stack up and their 172.x/10.88.x addresses appear alongside the real one, and picking those fails exactly the way localhost does. Override with OPENRESTO_DEV_HOST / OPENRESTO_API_PORT when the guess is wrong; the script exits rather than falling back to an address the phone cannot route to.

Which address that is comes from openresto-frontend/scripts/lib/expo-go.mjs, shared with npm run native:go rather than reimplemented — the two answer the same question, and answering it twice is how the answers drift. It asks the routing table (a connected UDP socket fixes the local end of a route without sending anything) and only falls back to filtering interface names. OPENRESTO_DEV_HOST is that lib's HOST_ENV, so both commands take the same override; the lib imports node builtins only, so the root npm test needs no frontend install.