Adding New Screens to the Mobile App

This guide walks you through adding new screens to the Launch mobile app, including proper navigation setup, route registration, and navigation guards.

Overview

The Launch mobile app uses a nested navigation structure with NativeTabs inside an AppStack:

AppStack (main navigation)
├── Authentication routes (/auth/*)
├── Onboarding routes (/onboarding/*)
├── (tabs) ← NativeTabs navigator
│   ├── index (Home)
│   ├── explore (Features)
│   └── profile (Profile)
└── Modal/Feature screens (/payments, etc.)

Prerequisites

Expo Router basics
App running locally

Steps

Step-by-Step Process

1. Create the Screen Component

Create your screen file in the app/ directory: File: apps/mobile/app/your-screen.tsx

import { View } from "react-native";
import { useTheme } from "heroui-native";
import { AppText } from "@/components/app-text";
import { ScreenContainer } from "@/components/screen-container";

export default function YourScreen() {
  const { colors } = useTheme();

  return (
    <ScreenContainer style={{ backgroundColor: colors.background }}>
      <View className="px-5 py-6">
        <AppText className="text-3xl font-bold mb-2">Your Screen Title</AppText>

        <AppText className="text-lg text-muted-foreground mb-6">
          Screen description or subtitle.
        </AppText>

        {/* Your screen content here */}
      </View>
    </ScreenContainer>
  );
}

2. Customize Screen Options (Optional)

Expo Router uses file-based routing, so your screen is registered automatically. If you want custom header options, add them to the layout: File: apps/mobile/app/_layout.tsx or apps/mobile/app/(tabs)/_layout.tsx

<Stack.Screen
  name="your-screen"
  options={{
    title: "Your Screen Title",
    presentation: "card",
    headerShown: true,
  }}
/>

3. Adjust Redirect Rules (if needed)

If the screen should be reachable during onboarding or auth flows, update the redirect logic in apps/mobile/lib/hooks/useAppNavigation.ts. To navigate to your screen from within tabs (like Explore): From within a tab screen:

import { useNavigation } from "@react-navigation/native";

const navigation = useNavigation();

const handleNavigate = () => {
  const parentNav = navigation.getParent();
  const grandParentNav = parentNav?.getParent();
  grandParentNav?.navigate("your-screen" as never);
};

Using FeatureCard component:

<FeatureCard
  title="Your Feature"
  description="Feature description"
  providers={providers}
  status="Not set up"
  buttonText="Explore Feature"
  onPress={handleNavigate}
/>

From Tabs to AppStack Routes

When navigating from inside tabs to AppStack routes, you need to access the grandparent navigator:

// Inside a tab screen (explore, profile, etc.)
const parentNav = navigation.getParent(); // Gets NativeTabs
const grandParentNav = parentNav?.getParent(); // Gets AppStack
grandParentNav?.navigate("your-screen" as never);

For routes at the same level in AppStack:

// Inside an AppStack screen
navigation.navigate("your-screen" as never);

Back navigation works automatically with the configured headerBackTitle:

iOS: Shows ”< Features” or custom back title
Android: Shows standard back arrow
Gesture: Swipe from edge works automatically

Screen Types and Presentations

Card Presentation (Recommended)

presentation: "card"; // Slides in from right, standard behavior

presentation: "modal"; // Slides up from bottom, modal-style

Fullscreen Presentation

presentation: "fullScreenModal"; // Full screen overlay

Navigation guards live in apps/mobile/lib/hooks/useAppNavigation.ts and handle:

Redirecting unauthenticated users to auth
Redirecting users with incomplete onboarding
Sending fully onboarded users to the main tabs

Common Issues and Solutions

Problem: Calling navigation.navigate() from inside tabs doesn’t work. Solution: Use grandparent navigation:

const parentNav = navigation.getParent();
const grandParentNav = parentNav?.getParent();
grandParentNav?.navigate("your-screen" as never);

Issue: Automatic Redirect Away from Screen

Problem: User gets redirected back to onboarding or tabs. Solution: Update redirect logic in useAppNavigation.ts so the new route is reachable for your target user state.

Issue: Wrong Back Button Text

Problem: Back button shows “(tabs)” or route name. Solution: Set custom back title:

headerBackTitle: "Features"; // Shows "< Features"

Best Practices

1. Consistent Screen Structure

Use ScreenContainer for layout consistency
Follow the established padding/margin patterns
Use theme colors via useTheme()

Use kebab-case for route names: "feature-name"
Keep route names descriptive but concise
Match file names to route names when possible

3. Header Configuration

Always set meaningful title
Use appropriate presentation for UX
Customize headerBackTitle for better navigation context

Update redirect rules in useAppNavigation.ts when adding new flows
Consider authentication requirements
Test navigation flows thoroughly

Example: Complete Feature Screen

Here’s a complete example following all best practices: File: apps/mobile/app/ai-chat.tsx

import { View } from "react-native";
import { useTheme } from "heroui-native";
import { AppText } from "@/components/app-text";
import { ScreenContainer } from "@/components/screen-container";

export default function AIChatScreen() {
  const { colors } = useTheme();

  return (
    <ScreenContainer style={{ backgroundColor: colors.background }}>
      <View className="px-5 py-6">
        <AppText className="text-3xl font-bold mb-2">AI Chat</AppText>

        <AppText className="text-lg text-muted-foreground mb-6">
          Configure AI providers for intelligent conversations.
        </AppText>

        {/* Provider selection and setup content */}
      </View>
    </ScreenContainer>
  );
}

AppStack Registration:

<Stack.Screen
  name="ai-chat"
  options={{
    title: "AI Chat",
    presentation: "card",
    headerShown: true,
    headerBackTitle: "Features",
  }}
/>

Navigation from FeatureCard:

<FeatureCard
  title="AI Chat"
  description="Multi-model AI conversations with Claude and OpenAI"
  providers={aiProviders}
  status="Coming soon"
  buttonText="Explore AI Chat"
  onPress={() => {
    const parentNav = navigation.getParent();
    const grandParentNav = parentNav?.getParent();
    grandParentNav?.navigate("ai-chat" as never);
  }}
/>

This pattern provides a consistent, maintainable approach to adding new feature screens to the Launch mobile app.

Troubleshooting

Screen not accessible: check route group and auth/onboarding guards
Header not updating: update the correct layout file

​Adding New Screens to the Mobile App

​Overview

​Prerequisites

​Steps

​Step-by-Step Process

​1. Create the Screen Component

​2. Customize Screen Options (Optional)

​3. Adjust Redirect Rules (if needed)

​4. Add Navigation from Other Screens

​Navigation Patterns

​From Tabs to AppStack Routes

​Direct AppStack Navigation

​Back Navigation

​Screen Types and Presentations

​Card Presentation (Recommended)

​Modal Presentation

​Fullscreen Presentation

​Navigation Guards

​Common Issues and Solutions

​Issue: Navigation Not Working from Tabs

​Issue: Automatic Redirect Away from Screen

​Issue: Wrong Back Button Text

​Best Practices

​1. Consistent Screen Structure

​2. Navigation Naming

​3. Header Configuration

​4. Navigation Guards

​Example: Complete Feature Screen

​Troubleshooting

​Next Steps

Adding New Screens to the Mobile App

Overview

Prerequisites

Steps

Step-by-Step Process

1. Create the Screen Component

2. Customize Screen Options (Optional)

3. Adjust Redirect Rules (if needed)

4. Add Navigation from Other Screens

Navigation Patterns

From Tabs to AppStack Routes

Direct AppStack Navigation

Back Navigation

Screen Types and Presentations

Card Presentation (Recommended)

Modal Presentation

Fullscreen Presentation

Navigation Guards

Common Issues and Solutions

Issue: Navigation Not Working from Tabs