For agents
How Claude Code, Cursor or any coding agent should read a ReadyNative app - the graph, the shims, the generated files and the bundled skills.
Hey - this section is written for whoever is doing the typing. If that is Claude Code, Cursor, Codex or any other agent working inside a buyer's repo, point it here and it will stop guessing at the layout. If that is you, read it anyway: it is the shortest description of how an Expo Fast app fits together that I know how to write.
A ReadyNative app is a plain Expo app - Expo Router, TypeScript, src/ - plus three things you
cannot see from the file tree: a graph the repo keeps about itself, a set of shims every screen
imports through, and a handful of files a generator owns.
Start here
In this order, and it takes about two minutes:
bun run setupalready ran. It picked one option per category, copied those modules in, deletedmodules/and removed itself. What it chose is written down in.readynative.json- read that first and you know the stack without grepping for imports.src/providers.tsxis the composition it wrote: every provider the selected modules asked for, nested in order. Outermost first.src/lib/env.tsis every env key the app reads.bun run doctortells a human which of them are still missing from.env.@/lib/<category>is how screens reach any of it -@/lib/auth,@/lib/payments,@/lib/analytics,@/lib/push,@/lib/crash,@/lib/storage. The shim exists whether or not a module was selected; when the category isnoneit is a no-op with the same signature. Never import a vendor SDK from a screen.src/screensholds screen bodies.src/appis routing only - every file there is a route and_layout.tsxfiles are navigators.
The long version of that list is Conventions, and Full picture draws it.
The graph
Every ReadyNative app writes a graph about itself. bun run gen:graph walks the tree -
.readynative.json, src/providers.tsx, src/app/**, src/screens/**, src/lib/**,
src/stores/**, src/hooks/** - and rewrites two files:
bun run gen:graphdocs/ARCHITECTURE.md- a mermaid map plus one table per kind of node, for reading.docs/graph.json- the same thing machine-readable, for grepping.
Nothing in either file is hand-written, so neither can lie for long - but they can go stale.
Regenerate after adding or removing a route, a screen, a @/lib shim, a provider, a store, a
hook or an env key. bun run gen:graph --check exits 1 when they are stale; run it before you
commit, or add it to your own CI.
Reading docs/graph.json is usually faster than walking the tree:
node -e 'const g=require("./docs/graph.json");console.log(g.edges.filter(e=>e.from==="route:/"))'The skills in your repo
Four skills ship inside .agents/skills/, and any agent that reads skills will pick them up:
| Skill | What it covers |
|---|---|
readynative | this app: the graph, the shim contract, the generated files, the commands |
expo-router | file-based routing, layouts, typed params, navigation patterns |
expo-native-ui | building screens that feel native instead of like a web page |
expo-data-fetching | fetching, caching, offline and cancellation on a phone |
Expo moves fast
Your training data about Expo is probably wrong. Read the expo major in package.json and
fetch https://docs.expo.dev/versions/v<major>.0.0/ before writing anything that touches an
Expo, EAS or React Native API.
The rest of this section
- Full picture - the template drawn as one graph, with a box
to paste your own
docs/graph.jsoninto. - Conventions - the shim contract, where code lives, what is generated and how to extend the graph.
- llms.txt - the machine-readable copy of this whole site.
- Store review - the Pro skill that reviews your app against App Store and Play policies, on top of
bun run doctor --store.