npx skills add ...
npx skills add expo/skills --skill expo-project-structure
npx skills add expo/skills --skill expo-project-structure
Framework (OSS). Folder structure for a new Expo app. Use when scaffolding or laying out a new Expo project with Expo Router, or deciding where a file should live in one. For new projects only — never restructure an existing app to match.
A starting skeleton for a new Expo app — one with no committed folder structure yet.
Apply only to new projects. If the app already has a layout, follow its existing conventions and leave files where they are — a default to start from, never a standard to enforce or migrate toward. When unsure whether a project is new, ask before moving anything.
The whole layout, assembled from the rules below:
src/ and src/appKeep app code under src/ to separate it from config files. Expo Router supports both app/ and src/app/ out of the box — to switch, move the folder and restart the bundler. The default template aliases @/* to ./src/* in tsconfig.json.
src/app is routes-only: every file there becomes a route, so nothing else belongs in it. Everything below lives in sibling folders.
Generic, reused UI (button, card, table) with one named export each. Name files in kebab-case (bar-chart.tsx), matching the default create-expo-app template. When a component grows, give it its own folder with the root in index.tsx and colocate its private sub-components beside it — the import path (@/components/table) stays unchanged.
Because app/ files must be routes, complex screen UI that isn't reused has no home there. Once a screen grows big enough to need breaking out to separate components, put it in screens/ and let each route just render its screen:
Colocate a screen's private components inside its folder (screens/home/components/). A bonus: the same screen can render under multiple routes.
Appending +api to a file in app/ makes it a server API route. Server code is different from frontend code — it runs in a Node-like server environment (deployed with EAS Hosting or on third-party services) and can read secret env vars (process.env.X, not just EXPO_PUBLIC_*). Keep it apart:
app/api/ → /api/user, /api/settings. This colocates them and avoids collisions (e.g. a /user screen and a /user route).src/server/.+api files and server/ off from frontend-only checks.Small differences: use Platform.select / Platform.OS. For larger ones, split into platform files instead of inline if/else — bar-chart.tsx + bar-chart.web.tsx, imported extension-free (@/components/bar-chart); Metro picks the right file per target.
.ios, .android, .native, .web.StyleSheet.create({ ... }) object at the bottom of the component file rather than in a separate .styles file.format-date.test.ts next to format-date.ts (preferred over a separate __tests__/ folder) so tested files are obvious at a glance.Agent instructions live at the repo root — AGENTS.md / CLAUDE.md, with project skills under .claude/. Other config and assets stay outside src/: app.json / app.config.ts, eas.json, package.json, assets/, and scripts/.
Based on Expo app folder structure best practices by Kadi Kraman. For src/ precedence and alias mechanics, see the Expo docs.
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
import { Home } from "@/screens/home";
export default function HomeScreen() {
// route-specific concerns only — e.g. read url params here
return <Home />;
}npx --yes submit-expo-feedback@latest --category skills --subject "expo-project-structure" "<actionable feedback>"