Ship Maintainable React Native Apps
shares
If you’re building React Native apps meant to last, this guide is for you. Written with engineers, SDETs, and lead devs in mind, it covers four essentials: rock-solid navigation and login flow rules, smart component design with maintainable code patterns, practical TypeScript tips and typing examples, and a scalable styling approach built from Primitive → Base → Variant → Screen. The goal? Clear, real-world guardrails that keep your app healthy for the long run — without drowning in over-engineering.
This post builds naturally on my earlier piece on building a production-ready React Native app, which focused on setting up a solid foundation before writing any UI code.
TL;DR (quick overview)
- Navigation best practices: predictable navigator trees, minimal nesting, modular stack/tab files, avoid conditional switching inside render.
-
Component & code quality: follow SOLID principles, choose appropriate state management (Context vs Redux), optimize performance using RN APIs, and leverage
patch-packagecarefully. -
TypeScript usage: type public props and domain models, prefer
interfacefor extensibility, useenumandtypejudiciously, apply generic types for HOCs(Higher-Order Components). - Styles & colors: centralize fonts, colors, and follow a scalable Primitive→Base→Variant→Screen pattern when warranted.
1. Navigation Best Practices
Why follow these rules?
- Navigation is the user’s mental model of your app; inconsistent nav leads to state/UX bugs and hard-to-reproduce routing issues.
- Simple, predictable navigator topology makes deep linking, analytics, and testing straightforward.
- Minimizing navigator nesting reduces lifecycle and performance surprises (screen unmounting, tab state loss, duplicate headers).
Rules & When-To-Use
-
Avoid conditional navigator switching for login : Use
initialRouteName. Use conditional rendering only for entirely different app shells (e.g., separate consumer + admin apps). For normal auth flows, set the initial route based on auth state at startup, this keeps navigator tree stable. -
Prefer a single main navigator where possible. Have one
RootNavigatorthat composes stacks/tabs/drawer; it's easier to reason about deep linking and header options. -
Keep navigators modular : Separate files per stack/tab (e.g.
AuthStack.tsx, MainTabs.tsx). This avoids a monolithicAppNavigatorfile . -
Use
@react-navigation/native-stackfor performance and native-like transitions (when you need better native feel and lower overhead). - Do not nest more than 2–3 navigators (max 4 with Drawer). Excessive nesting complicates back behavior and header control.
- Bottom Tabs:
-
Use nested Stack inside a Bottom Tab for per-tab flows (e.g.,
HomeTab -> HomeStack). -
Use
react-native-safe-area-contextAPIs to handle safe area insets and avoid tab layout/style issues on devices with gestures/home indicator.
Minimal example (Auth + Main)
// navigation/RootNavigator.tsx
import React from "react";
import { NavigationContainer } from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import AuthStack from "./AuthStack";
import MainTabs from "./MainTabs";
const Stack = createNativeStackNavigator();
export default function RootNavigator({
isAuthenticated,
}: {
isAuthenticated: boolean;
}) {
return (
<NavigationContainer>
<Stack.Navigator
initialRouteName={ isAuthenticated ? "Main" : "Auth"}
screenOptions={{{ headerShown: false }}}
>
<Stack.Screen name="Auth" component={AuthStack} />
<Stack.Screen name="Main" component={MainTabs} />
</Stack.Navigator>
</NavigationContainer>
);
}
Why not conditional switching inside render? If you swap between entirely different navigator trees in render, you reset navigation state, break back-button expectations (Android), and harm analytics/metrics continuity.
TypeScript for Navigation: Full Type Safety
Implement comprehensive TypeScript for navigation to catch route name typos and ensure correct parameters :
// types/navigation.ts
export type RootStackParamList = {
Auth: undefined; // No parameters expected
Main: undefined;
Profile: { userId: string };
Settings: { refresh?: boolean };
};
// screens/ProfileScreen.tsx
import type { NativeStackScreenProps } from "@react-navigation/native-stack";
type ProfileScreenProps = NativeStackScreenProps<RootStackParamList, "Profile">;
function ProfileScreen({ route, navigation }: ProfileScreenProps) {
// route.params.userId is now properly typed as string
const { userId } = route.params;
return (
<View>
<Text>User ID: {userId}</Text>
</View>
);
}
For nested navigators, use
NavigatorScreenParams to maintain type safety :import { NavigatorScreenParams } from "@react-navigation/native";
type TabParamList = {
Home: NavigatorScreenParams<StackParamList>;
Profile: { userId: string };
};
2. Component & Code Quality
High-level goal: Single Responsibility + composition over inheritance. Components should do one thing and be easy to test.
SOLID principles (practical mapping)
-
Single Responsibility: A component should have only one clear job. If your
ProfileScreenhandles layout, API calls, and form validation all at once, it’s taking on too much. Break it down into smaller parts:ProfileScreen(layout),useProfileData(API logic), andProfileForm(form handling). This makes each piece easier to test and maintain. -
Open/Closed: Components should be easy to extend but shouldn’t need constant rewriting. Instead of editing the Button component every time you want a new style, pass variations as props:
<Button variant="primary" />or build on top of it:<IconButton icon="home" />that wraps the base button. -
Liskov Substitution Subcomponents should work anywhere their parent component works. For example, if
PrimaryButtonextendsBaseButton, you should be able to usePrimaryButtonanywhereBaseButtonis expected without breaking anything. -
Interface Segregation: Don’t make a component accept a long list of props it doesn’t always need. Instead of one giant component with 20+ props for different cases, make smaller, focused ones:
ListComponentfor lists,GridComponentfor grids,DetailComponentfor details—each with only the props they need. -
Dependency Inversion: Rely on general rules or abstractions, not specific tools. Instead of calling
axios.get()directly in your component, use an abstraction likeuseApi:
const { data } = useApi('users');
This way, switching API libraries or implementations is painless.
State management: Redux vs Context API
- Context API
- Good for small-to-medium apps, theme/user preferences, and local scoped state .
- Avoid storing frequently updated large objects in context (causes re-renders).
- Redux (or other external store)
- Preferred when you need predictable, traceable updates, advanced middlewares, time-travel, or when many distant parts of the tree must access & update the same state frequently .
- Organize your Redux slices by feature for better maintainability .
Rule of thumb: Start with local state + context. Introduce global stores when complexity or performance demands it.
Performance & React Native APIs You Should Know
(And yes, always read the official docs!)
InteractionManager
- What it does: Runs heavy tasks only after animations or gestures finish.
- In simple terms: It’s like telling your app, “Wait until the animation is done before doing this heavy work,” so the UI stays smooth.
- Use case: When you need to process data or do complex calculations that might cause the app to lag if done during animations.
FlatList (for long lists)
-
What to use:
keyExtractor, getItemLayout, initialNumToRender,andwindowSize. - In simple terms: FlatList is smart — it only renders what’s visible on screen instead of the entire list at once.
- Use case: Perfect for chats, product feeds, or any large scrollable list — smooth and efficient.
ScrollView
-
What to avoid: Don’t use ScrollView for loading huge lists. Use
FlatListorSectionListinstead. - In simple terms: ScrollView loads everything at once (like one long web page), while FlatList loads items as you scroll (like a social media feed).
- Use case: Great for short, static screens (like settings or forms). For endless lists, go with FlatList.
Patches & patch-package
-
Use
patch-packagewhen you must fix a bug in an upstream npm module quickly. -
Commit patch under version control (e.g.,
patches/), and add topostinstallscript. - Caveat: Patches increase maintenance cost. Open PRs upstream and track upstream releases to remove patches later.
Example postinstall script
{
"scripts": {
"postinstall": "patch-package"
}
}
3. TypeScript : Use It Wisely
Why TypeScript
- Catches a majority of class of runtime bugs early, improves DX, and makes refactors safer .
- In 2025, TypeScript is the de facto standard for production React Native apps .
Use TypeScript wisely
- Prefer typing public component props and critical domain models. Don’t over-type internal ephemeral variables.
- Keep types local where they belong; export only domain or shared types.
enum vs type vs interface
-
enum: Use sparingly for runtime values you need (e.g.,enum ScreenName { Home = 'Home' }). Noteenumemits JS. -
type: Flexible unions, mapped types, and complex shapes. Good for composing unions:type ID = string | number. -
interface: Extendable and better for object shapes you expect to extend (public API surface). Preferinterfacefor public component props that might be extended .
Component & HOC(Higher-Order Component) typing examples
// typed component with default props and children
interface ButtonProps {
title: string;
onPress?: () => void;
disabled?: boolean;
children?: React.ReactNode;
}
const Button: React.FC<ButtonProps> = ({
title,
onPress,
disabled = false,
children,
}) => {
return (
<TouchableOpacity onPress={onPress} disabled={disabled}>
<Text>{title}</Text>
{children}
</TouchableOpacity>
);
};
// Custom hook with TypeScript
function useFetchUser(id: string) {
const [user, setUser] = useState<User | null>(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
fetchUser(id)
.then(setUser)
.finally(() => setLoading(false));
}, [id]);
return { user, loading };
}
// HOC(Higher-Order Component)
function withBackground<P extends object>(
Wrapped: React.ComponentType<P>,
bgColor: string
) {
return (props: P & ViewProps) => (
<View style={[{ backgroundColor: bgColor }, props.style]}>
<Wrapped {...props} />
</View>
);
}
// Usage of HOC
const CustomText = (props: { text: string }) => <Text>{props.text}</Text>;
const BlueBackgroundComponent = withBackground(CustomText, "lightblue");
export default function App() {
return (
<SafeAreaView style={{ flex: 1 }}>
<BlueBackgroundComponent text="Hello with background!" />
</SafeAreaView>
);
}
Tip: When writing HOCs, accept a generic <P> to preserve wrapped component props. For complex cases, prefer hooks to HOCs , hooks compose better and are easier to type.
Additional TypeScript tips:
- Create strict interfaces for props to prevent passing incorrect values
-
Use
typeoffor deriving types from existing JavaScript objects -
Create a dedicated
typesfolder for shared type definitions
4. Styles & Color
High-level principle: Do not hard-code fonts/colors in components.
Simple config layout
src/
├─ config/
│ ├─ colors.ts
│ └─ fonts.ts
Example colors.ts
export const colors = {
primary: "#0A84FF",
background: "#FFFFFF",
text: {
primary: "#111111",
secondary: "#666666",
},
// semantic
success: "#28A745",
error: "#E53935",
};
export type Colors = typeof colors;
Example fonts.ts
export const fonts = {
regular: "Inter-Regular",
medium: "Inter-Medium",
bold: "Inter-Bold",
};
Primitive → Base → Variant → Screen pattern (use only when needed)
- Primitive: raw building blocks (Text, View, Image) with minimal props.
- Base: slightly opinionated components (BaseButton, BaseText) that enforce spacing and accessibility defaults.
- Variant: theme-aware variations (PrimaryButton, GhostButton).
- Screen: compose variants into real screens.
When to use: This adds value at scale, when you have many screens and many designers. For small teams, stick to Primitives + Base components and a small set of Variants.
Example of the pattern in practice:
export const theme = {
colors: {
primary: "#0A84FF",
background: "#FFFFFF",
text: {
primary: "#111111",
secondary: "#666666",
},
semantic: {
success: "#28A745",
error: "#E53935",
},
},
spacing: {
xs: 4,
sm: 8,
md: 16,
lg: 24,
xl: 32,
},
borderRadius: {
sm: 4,
md: 8,
lg: 16,
},
typography: {
body: {
fontSize: 16,
fontFamily: "Inter-Regular",
},
heading: {
fontSize: 24,
fontFamily: "Inter-Bold",
},
},
};
// 1. Primitive components
const BaseText = ({ children, style }) => { = {
return <Text style={style}>{children} </Text>
};
// 2. Base components with default styles
const BaseButton = ({ children, onPress, style }) => {
const theme = useTheme();
return (
<TouchableOpacity
onPress={onPress}
style={[
{
padding: theme.spacing.md,
borderRadius: theme.borderRadius.sm,
backgroundColor: theme.colors.primary,
},
style,
]}
>
<BaseText>{children}</BaseText>
</TouchableOpacity>
);
};
// 3. Variant components
const PrimaryButton = (props) => {
return <BaseButton {...props} />;
};
const SecondaryButton = ({ ...props }) => {
const theme = useTheme();
return (
<BaseButton
{...props}
style={{
backgroundColor: "transparent",
borderWidth: 1,
borderColor: theme.colors.primary,
}}
/>
);
};
// 4. Screen composition
const ProfileScreen = () => {
return (
<View>
<PrimaryButton ondivss={() => {}}>Save Changes</PrimaryButton>
<SecondaryButton onPress={() => {}}>Cancel</SecondaryButton>
</View>
);
};
Don’t overengineer. The Primitive→Base→Variant→Screen pipeline costs cognitive overhead, use it when your app count or complexity warrants (~100 screens or cross-product design consistency).
Conclusion
Keep your navigation predictable, components single-purpose, types intentional, and styles centralized. Start small: apply colors, fonts, partition navigator files, type your public props, and only adopt the Primitive→Base→Variant pattern when your app size justifies it. These lightweight guardrails give you maintainability without the cost of premature architecture.