expo-next-router 🚀

Library that brings the familiar Next.js file-based routing conventions to Expo Router projects. By introducing an intermediate pages/ folder, it guarantees that only page, layout, and not-found files turn into routes—so you can confidently keep child components, hooks, and utilities right beside the page file without polluting Expo Router.

Why it helps 🌟

• Mirrors the Next.js feature folder layout to reduce onboarding friction.
• Prevents auxiliary components from unintentionally becoming Expo routes.
• Syncs files between pages/ and app/ automatically, optionally in watch mode.
• Removes orphaned route files and empty folders to keep the project tidy.
• Works with both JavaScript and TypeScript projects out of the box.

Installation 📦

npm install --save-dev expo-next-router

Using Yarn:

yarn add --dev expo-next-router

Configuration ⚙️

Create an expo-next-router.config.js (or .mjs, .cjs, .json) at the project root:

module.exports = {
  watch: true,
  verbose: true,
  extensions: ["js", "jsx", "ts", "tsx"],
  appDir: "example/app",
  workDir: "example/pages",
};

Available options

| Key | Type | Default | Description | | ------------ | ---------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | watch | boolean | false | Enables the watcher so routes stay in sync with workDir on every change. | | verbose | boolean | false | Prints colorful logs for watcher events. | | extensions | string[] | ["js", "jsx", "ts", "tsx"] | File extensions considered during sync. | | appDir | string | — | Target Expo app/ directory. Accepts relative or absolute paths. | | workDir | string | — | Source folder with Next.js-style files (page, layout, not-found). Accepts relative or absolute paths. |

appDir and workDir must be provided. The remaining options have defaults and can be omitted.

Usage ▶️

Run the sync through the CLI:

npx expo-next-router

• Reads the config file, mirrors page, layout, and not-found files into app/, and removes orphaned routes.
• When watch: true, a watcher observes workDir and keeps routes synchronized automatically.

For day-to-day development, add concurrently to your package.json so the router runs alongside expo start:

{
  "scripts": {
    "start": "concurrently \"npx expo-next-router\" \"expo start\""
  }
}

Recommended structure

project/
├─ app/             # generated automatically; do not edit manually
├─ pages/           # build your features here
│  ├─ page.tsx
│  ├─ layout.tsx
│  └─ about/
│     └─ page.tsx
│     └─ Form.tsx   # common components will not generate route
└─ expo-next-router.config.js

Inside pages/, feel free to add any other files or components without the reserved filenames (page, layout, not-found); they remain ordinary modules you can import.

Support and contributions 🤝

Open an issue at https://github.com/joalisonpereira/expo-next-router/issues for questions, suggestions, or bug reports. Pull requests are welcome!