Getting Started

This guide walks through setting up @teardown/navigation in a React Native project.

Prerequisites

React Native 0.72+
React Navigation 7+
Node.js 18+

Installation

Core Dependencies

# Navigation packages
bun add @teardown/navigation @react-navigation/native @react-navigation/native-stack

# Required React Navigation dependencies
bun add react-native-screens react-native-safe-area-context

Metro Plugin

The Metro plugin scans your route files and generates TypeScript types:

bun add -D @teardown/navigation-metro

Optional Navigators

Install based on your needs:

# Tab navigation
bun add @react-navigation/bottom-tabs

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

Project Setup

1. Metro Configuration

Create or update metro.config.js:

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

const config = getDefaultConfig(__dirname);

module.exports = withTeardownNavigation(config, {
  // Optional: Override defaults
  routesDir: "./src/_routes",
  generatedDir: "./.teardown",
  verbose: false,
});

2. Create Routes Directory

mkdir -p src/_routes

3. Create Root Layout

The root _layout.tsx defines your app's navigator structure:

// src/_routes/_layout.tsx
import { defineLayout } from "@teardown/navigation";

export default defineLayout({
  type: "stack",
  screenOptions: {
    headerShown: true,
    animation: "slide_from_right",
  },
});

4. Create Home Screen

// src/_routes/index.tsx
import { View, Text } from "react-native";
import { defineScreen } from "@teardown/navigation";

function HomeScreen() {
  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Text>Welcome Home</Text>
    </View>
  );
}

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

5. Create Router Component

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

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

6. Use Router in App Entry

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

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

Generated Files

When you run the Metro bundler, the plugin generates files in .teardown/:

File	Purpose
`routes.generated.ts`	Route parameter types
`routeTree.generated.ts`	Navigator tree structure
`linking.generated.ts`	Deep linking configuration
`register.d.ts`	Type augmentation for hooks
`manifest.json`	Route metadata

Add .teardown/ to your .gitignore:

# Generated navigation files
.teardown/

Configuration Options

The withTeardownNavigation function accepts these options:

Option	Type	Default	Description
`routesDir`	string	`"./src/_routes"`	Path to routes directory
`generatedDir`	string	`"./.teardown"`	Output path for generated files
`prefixes`	string[]	`[]`	Deep link URL prefixes
`verbose`	boolean	`false`	Enable verbose logging
`autoTemplate`	boolean	`true`	Auto-populate new route files
`usePolling`	boolean	`false`	Use polling for file watching

Options can also be set in teardown.config.ts:

// teardown.config.ts
export default {
  name: "MyApp",
  slug: "myapp",
  navigation: {
    routesDir: "./src/_routes",
    generatedDir: "./.teardown",
    verbose: false,
  },
};

Verifying Setup

Start the Metro bundler:

bun run dev
# or
npx react-native start

Check that .teardown/ is generated with type files
Navigate in your app - you should see the home screen

Next Steps

File-Based Routing - Learn route file conventions
Type-Safe Navigation - Use typed navigation hooks
Layouts - Configure navigators

On this page