Navigation

@teardown/navigation provides type-safe, file-based navigation for React Native applications using React Navigation under the hood.

⚠️ Early Development - The Teardown SDKs and APIs are under active development. Expect frequent breaking changes. Not recommended for production apps.

Features

File-based routing - Define routes by creating files in src/_routes/
Full type safety - Route params, navigation methods, and hooks are all type-checked
React Navigation v7+ - Built on top of React Navigation for reliability
Stack, Tab, and Drawer - Support for all common navigator types
Deep linking - Automatic deep link configuration generation
Hot reloading - Route changes detected and types regenerated in development

Installation

Install the navigation packages:

bun add @teardown/navigation @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context

Add the Metro plugin for type generation:

bun add -D @teardown/navigation-metro

Optional Navigators

Install additional navigators as needed:

# For tab navigation
bun add @react-navigation/bottom-tabs

# For drawer navigation
bun add @react-navigation/drawer react-native-gesture-handler react-native-reanimated

Quick Start

1. Configure Metro

Update your metro.config.js:

const { getDefaultConfig } = require("@react-native/metro-config");
const { withTeardownNavigation } = require("@teardown/navigation-metro");

const config = getDefaultConfig(__dirname);

module.exports = withTeardownNavigation(config);

2. Create Routes

Create your routes in src/_routes/:

src/_routes/
├── _layout.tsx    # Root layout (stack navigator)
├── index.tsx      # Home screen (/)
├── settings.tsx   # Settings screen (/settings)
└── users/
    ├── _layout.tsx   # Users layout
    ├── index.tsx     # Users list (/users)
    └── [userId].tsx  # User profile (/users/:userId)

3. Define Screens

// src/_routes/index.tsx
import { defineScreen } from "@teardown/navigation";

function HomeScreen() {
  return <View><Text>Welcome Home</Text></View>;
}

export default defineScreen({
  component: HomeScreen,
  options: { title: "Home" },
});

4. Create Router

// src/app/index.tsx
import { createTeardownRouter } from "@teardown/navigation";
import { routeTree } from "../.teardown/routeTree.generated";

export const Router = createTeardownRouter({
  routeTree,
  initialRouteName: "index",
});

5. Use in App

// App.tsx
import { Router } from "./src/app";

export default function App() {
  return <Router />;
}

Next Steps

Getting Started - Detailed setup guide
File-Based Routing - Route file conventions
Type-Safe Navigation - Using typed hooks
Layouts - Stack, Tab, and Drawer navigators

On this page