bennykok/omg.dev/omg-app-builder

Build and deliver an omg.dev app

Turn the user's product description into a working, verified result. Keep setup work with the agent. Ask only about product choices that materially change the result.

Ask one question per question call, and put at most one decision in it. A second question in the same call is not shown to the user on every client. If the user has not said what the app should do, ask that in plain words and wait for the answer. Do not build a placeholder product in its place. If a question times out, ask again once in a normal message and end the turn.

Establish the project

• In Quick Chat, call omg_create_project once with a short descriptive name. Set template to expo for an Expo or universal mobile app. The Expo template already contains a working todo flow with data stored on the phone, Expo Router, Liquid Glass, Lucide icons, web support, and EAS configuration. Use the returned repo.cwd for every command, edit, check, and deployment. Inspect omg_list_repos before retrying an uncertain create call.
• In a New Project session, the current directory is already the project. It contains Git, a README, and this skill. Do not create a second project.
• Preserve .git. Do not overwrite an existing folder or move the current Quick Chat into the new project.

Choose the delivery path

• For a website, web app, or API, use the supported omg.dev runtime unless the user requests another platform. In a blank project, scaffold the official omg.dev React template before writing product code. The current directory already contains Git and omg.dev instructions, so generate into a temporary directory inside it, copy the scaffold into the project, and remove only that temporary directory:

``bash scaffold="$(mktemp -d .omg-web-scaffold-XXXXXX)" bunx --bun create-omg@latest "$scaffold" --template react-ts --no-install cp -a "$scaffold"/. . rm -rf "$scaffold" bun install ``

This template supplies @omg-dev/vite-plugin, vibes-build, server functions, database support, and analytics. Do not substitute create-vite or a hand-written Vite scaffold. Read https://docs.omg.dev/llms.txt and only the relevant parts of https://docs.omg.dev/llms-full.txt before choosing additional packages or API contracts.

• For a game (racing, arcade, puzzle, kids' learning, word, 3D), create the project with template: "web-game" and read .agents/skills/omg-web-game-builder/SKILL.md instead of designing an engine. Its step 1 comes before any code edit: bun run dev in the background on port 5174, then omg_expose_port with port 5174 and without expoGo, then tell the user the preview is ready in the card below. The Expo preview steps in this skill (port 8081, expoGo: true) do not apply to a web game. Use template: "expo-game" and .agents/skills/omg-game-builder/SKILL.md only when the user asks for a game to install on iPhone or Android, or names Expo or a native app.
• For an Expo app, start from the managed expo template and follow "Expo app: the fast path" below. Adapt its screens and its data store instead of rebuilding configuration. Keep secrets in hosted server routes. A production native build needs any server deployed at a secure origin; do not treat a sandbox tunnel as production hosting.
• Use one live Metro server for Expo Web and Expo Go in a Cloud Computer. Expose its port through omg_expose_port; do not assume a global Expo CLI, Xcode, a simulator, or machine-specific tools exist.
• When the app is compatible with Expo Go, omg_expose_port puts the exps:// Expo Go link on a preview card in the omg.dev app. Tell the user the preview is ready and to open it from the card below. Do not paste the raw exps:// URL in your reply; the card already shows it. Paste it only where the user cannot see the card, such as a reply sent with omg_send_to_origin to a messaging channel, or when the user asks for the link. Do not use Expo tunnel, LAN exposure, exp.direct, or ngrok. If Expo Go cannot load a required native module, use a development build when authorized or report that limit clearly.
• TestFlight, App Store submission, paid services, domains, and third-party production accounts are separate delivery actions. Do them only when the user requests them and the required account is available. TestFlight needs the user's Expo account and paid Apple Developer account, but an EAS cloud build does not need Xcode or a Mac in the sandbox. Use supported login flows and never ask for passwords or tokens in chat.

Expo app: the fast path

A new user is waiting. The first screen must reach their phone within about 3 minutes, before any feature work. Follow these steps in order:

1. omg_create_project with template: "expo". If node_modules is missing, run bun install once.
2. Preview before you write any code. Call omg_expose_port with port 8081 and expoGo: true. Then run bash scripts/start-expo-preview.sh <expoGo.proxyUrl> 8081 from the project directory, with a 240000 ms shell timeout. When it prints Sandbox proxy answers: HTTP 200, present the web preview first: "Your app is ready. The card below shows it running, and it works on any device." Then mention the phone in one sentence: "To try it on your own phone, tap Your phone on the card." When the omg_expose_port result has simulatorAvailable: true, add one more sentence: "You can also try it on an iPhone right in the card: tap Simulator." Do not promise the simulator when that field is false or missing. Do not paste expoGo.url; the card shows it. Metro reloads the app on every save, so the preview follows your edits from here on.
3. Write the screens, in a few larger edits rather than one small edit per turn. Replace the template home screen in src/app/index.tsx; do not add a second index route.
4. Run bun run typecheck and fix what it reports. It also checks the routes and fails on a second home screen or a root app/ folder. Then run bun run check:ui, open its PNGs, and fix what is wrong (see Build step 4). Do not write automated tests unless the user asks.
5. Deploy once with omg_deploy (see below). The data stays on the phone, so this is a static web build.
6. Finish with omg_ship.

Do not browse node_modules, fetch documentation, or read the template file by file before the first preview: the summary below is enough. Do not write your own browser test loops or screenshot scripts: bun run check:ui does that. If you cannot view images, read its text report only.

The template:

• src/app/index.tsx: the home screen, and the only file for /. Replace its content with your home screen. Keep every screen in src/app/: Expo Router ignores a root app/ folder while src/app exists. For tabs, move the home screen to src/app/(tabs)/index.tsx and delete src/app/index.tsx, because both answer / and the old one wins. The template file has a header, an input with an add button, a list with toggle and delete, an error card, and a reload button. Styles are in one StyleSheet at the bottom; the theme constants are at the top (INK, CORAL, BACKGROUND, SURFACE, SURFACE_BORDER).
• src/app/_layout.tsx: an Expo Router stack with no header, inside KeyboardProvider. A new screen is a new file in src/app/ (stats.tsx is /stats). Navigate with router.push("/stats") or <Link href="/stats"> from expo-router.
• src/lib/tasks.ts: the data, stored on the phone with AsyncStorage (localStorage on the web). tasksApi.list(), create(title), update(id, patch), remove(id). Keep this file. For each new kind of item, copy its shape with its own storage key.
• Icons: lucide-react-native, for example <Plus color={CORAL} size={22} />. Glass surfaces: GlassView from expo-glass-effect.
• Colours: set every theme constant from the design before you style screens. Cards, rows and sheets use the design's own surface colour. The template's translucent white SURFACE suits only its light starter; left on a dark or coloured design, every card comes out white. Use GlassView only where the design shows frosted glass. On Android it draws no glass, so give it a background colour.
• Safe areas: wrap each screen in SafeAreaView from react-native-safe-area-context with edges={["top", "bottom"]}, or use useSafeAreaInsets(). Never import SafeAreaView from react-native: it is iOS-only, so on Android the header goes under the status bar and the tab bar under the gesture bar.
• Keyboard: put screens with a text input in KeyboardAwareScrollView from src/lib/keyboard (bottomOffset={24}, keyboardShouldPersistTaps="handled"), as the template does. For a field pinned to the bottom, use KeyboardStickyView from the same file. Import them from src/lib/keyboard, never from react-native-keyboard-controller directly: its .web.tsx twin keeps the static web export working. Do not use React Native's KeyboardAvoidingView: on iOS the screen moves after the keyboard, slowly.

Data: store it on the phone by default, with the tasks.ts pattern. Use hosted data only when the user asks for accounts or data shared between people. Then add sign-in with @omg-dev/sdk and .scoped("user") collections in schema.ts. Never call /api/... with a raw fetch: a hosted collection answers an anonymous phone with 401 Authentication required.

For hosted data, install the latest @omg-dev/sdk and deploy the backend before testing its shared data in Metro. Keep .omg/project.json in the project directory. The hosted web preview uses that registered app identity and signs its owner in through the SDK. Use <VibesAuthProvider> and SDK requests. Do not add a separate preview login, forward dashboard cookies, or replace the user's app permissions. A physical phone still needs the app's normal sign-in and the deployed backend origin.

Metro rules: use only ports 8081 to 8099, because Expo Go links work only in that range. Start Metro only with the script; npx and ss are not installed on every Computer.

Building blocks (Expo)

The template ships tested helpers in src/kit/. Import them; do not rewrite them. They work on iOS, Android and web. Each file starts with a comment that shows its use.

• overlay.tsx: useConfirm() and useSheet(). <OverlayProvider> is already in _layout.tsx. Use if (await confirm({ title, destructive: true })) for every delete or confirm. Alert.alert with buttons does nothing on web. Use useSheet().open(node) for sheets and forms. Do not stack Modal components: the second one draws behind the first on web.
• ActionRow.tsx: a pressable row with a delete or other action beside it. A button nested inside a pressable row also fires the row on web.
• image.ts: await toPersistentImage(pickerAsset). Call the picker with base64: true, quality: 0.5 and store the returned string. A picker URI on web is a blob: URL that is gone after a reload.
• use-timer.ts: usePersistedTimer(key, durationMs) with start, pause, resume, reset, and formatClock. It stores the end time, so a reload does not reset it. Use it for every timer or countdown.
• use-viewport.ts: useViewport() and useIsWide(). In the static web export useWindowDimensions() can give width 0 on first render. Prefer flex and maxWidth; use the hook only when you need a number.

Shared data between people (a shared list, a trade, a group): use the hosted @omg-dev/sdk path in "Data" above. Do not write a local server. If a local server is unavoidable, answer OPTIONS and send these headers on every response: Access-Control-Allow-Origin with the request Origin (or *), Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS, and Access-Control-Allow-Headers: content-type,authorization. A missing PUT or DELETE fails only in the browser.

Build