Navigation includes more than tapping a button. A detail screen may open from a list, a notification, or an external URL. Expo-router helps organize those entry points through file-based routes while considering layouts and navigation history.
Connect Expo knowledge to your agent
For Codex, run the official Expo plugin command below in a terminal or find Expo through /plugins. For Claude Code, use claude plugin install expo@claude-plugins-official instead. Both plugin installs include Expo Skills and MCP configuration. Other Agent Skills clients can run npx skills@latest add expo/skills --skill '*', choose their client, and refresh the session. Installing the plugin does not itself build or publish an app.
codex plugin add expo@openai-curated
Open the existing Expo project and explicitly request expo-router, including the SDK version, target platforms, and relevant files.
Map routes before creating files
Adapt this first request to your project:
Use expo-router to add product listing, product details, and a settings entry to this app. Map route files to URLs while preserving the home route. Details take a product ID and support both list navigation and direct links. Check the SDK, then implement and explain how to verify back behavior, invalid IDs, and cold-start links.
Current Expo documentation uses src/app as the route directory; an existing project may use app. Inspect the actual structure before adding screens. Route directories should contain pages and special layout files, while ordinary components, utilities, and hooks belong elsewhere so they are not interpreted as routes.
Keep an index route matching the root URL. Parenthesized route groups organize screens without adding an ordinary URL segment. Dynamic parameter names should agree between the filename and the code that reads them. A short file-to-URL map often reveals conflicts before an agent generates many screens. For example, with src/app, src/app/products/index.tsx maps to /products, while src/app/products/[id].tsx maps to /products/42. Read id on the detail screen with useLocalSearchParams<{ id: string }>(), link to the actual product path from the list, and provide a clear fallback for an invalid ID. If the existing project uses app, keep its directory instead of creating a second route tree just to match this example.
Keep shared structure in layouts
The root _layout handles initialization and shared providers before routes render. Nested layouts organize stacks, tabs, or modal flows. Reuse the project's existing structure instead of wrapping each screen in an unrelated navigation container. Link-based navigation should preserve appropriate platform and interaction behavior.
Native tabs, preview menus, and some transitions have operating-system requirements. New skill examples cannot be copied indiscriminately into older SDKs. Expo Router Skill 1.0.1 requires SDK 56+ projects to import the relevant APIs from expo-router/react-navigation rather than directly from @react-navigation/*; check the matching documentation before copying that pattern into an older SDK. Avoid replacing the entire navigation architecture merely to add a detail screen.
Turn a route map into an acceptance table
Before implementation, list route file, expected URL, and entry method. For product details, include both list navigation and a cold start from an external link, plus the behavior for an invalid product ID. When renaming a screen, decide what happens to the old path so two inconsistent detail routes do not remain.
After implementation, enter the detail screen from a list with Link and verify that Back returns to the previous filter. To test a cold-start link in an installed development build, set your actual expo.scheme in app.json. Adding or changing that scheme requires rebuilding and installing the development build. The example below assumes myapp and product ID 42; run one command in your project terminal, replacing both the scheme and route with your own:
npx uri-scheme open myapp://products/42 --ios
# For an Android device or emulator, use --android instead.
Close the app and run the same command again. Check that it reaches product 42, login or initialization does not redirect to the wrong screen, and Back behaves as intended. If a cold-start detail screen has no useful parent to return to, check whether the layout needs a stable index anchor; a list-click test alone will not catch that. Expo Go uses a different exp://…/--/products/42 URL, so it does not replace a custom-scheme check in an installed development build. Refreshing /products/42 on web is a third, independent check. If the current SDK lacks a native tab or transition API in an example, preserve working navigation and consult version-specific documentation before introducing an incompatible dependency.
Diagnose a failed deep link by layer
When an external link fails, check whether the URL matches a route file, whether the dynamic parameter arrives, whether authentication or initialization redirects too early, and whether the destination handles missing data. Do not immediately replace the navigation container. When moving a page, consider redirects or compatibility for previously shared links; deleting an old file may break them. Keep those checks beside the route map so the next detail screen can use the same entry-point test.
Test Back on dynamic detail routes
A developer reproduced a nested Stack whose only initial screen was [userId]: /users/1 opened correctly, but Back landed on a second instance with no parameter. For similar route trees, opening the detail page is not enough. Enter from the parent list, use system Back and router.back(), and test a deep link separately. If a blank-param page appears, inspect the Stack’s initial route and static-entry design before changing the navigation hierarchy.