React Native Dev Tools

A development tools library for React Native (including Expo) that enables component preview functionality, similar to Storybook, directly in your app. Focus on a single component during development while maintaining access to your app's global context and providers.

Features

• 🎯 Component Isolation: Preview individual components in isolation during development
• 🔄 Fast Refresh Compatible: Works seamlessly with React Native's Fast Refresh
• 🌐 Global Context Access: Previewed components still have access to your app's providers (Theme, Auth, etc.)
• ⚡ Zero Runtime Overhead: Transformations happen at build time
• 🚀 Easy Setup: Just wrap your app and add preview() calls
• 📦 Works with Expo: Fully compatible with Expo projects
• 🔧 TypeScript Support: Full TypeScript support out of the box

Installation

npm install react-native-dev-tools
# or
yarn add react-native-dev-tools
# or
pnpm add react-native-dev-tools

Quick Start

1. Configure Metro

Update your metro.config.js:

const { getDefaultConfig } = require('expo/metro-config');
const withDevTools = require('react-native-dev-tools/metro-plugin');

const config = getDefaultConfig(__dirname);

module.exports = withDevTools(config);

2. Wrap Your App

Wrap your app with DevToolsProvider:

import { DevToolsProvider } from 'react-native-dev-tools';

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

3. Add Preview Calls

In any component file you want to preview:

import { preview } from 'react-native-dev-tools';

export function MyComponent({ title }: { title: string }) {
  return <View><Text>{title}</Text></View>;
}

// Register for preview
preview(() => <MyComponent title="Preview Example" />);

That's it! When you run your app in development mode, if a preview() call is detected, only that component will be rendered instead of your full app.

Usage Examples

Basic Component Preview

import { preview } from 'react-native-dev-tools';

export function Button({ title, onPress }: ButtonProps) {
  return <TouchableOpacity onPress={onPress}><Text>{title}</Text></TouchableOpacity>;
}

// Preview with sample props
preview(() => <Button title="Click Me" onPress={() => alert('Pressed')} />);

Preview with Context

Since previews render within your app's provider tree, they automatically have access to context:

import { preview } from 'react-native-dev-tools';
import { useTheme } from './ThemeContext';

export function Card({ title }: { title: string }) {
  const theme = useTheme(); // ✅ Works! Context is available
  return <View style={{ backgroundColor: theme.primary }}><Text>{title}</Text></View>;
}

preview(() => <Card title="Themed Card" />);

Preview with Navigation

When using DevToolsProvider, navigation hooks work automatically:

import { preview } from 'react-native-dev-tools';
import { useNavigation } from '@react-navigation/native';

export function DetailsScreen() {
  const navigation = useNavigation(); // ✅ Works!
  // ...
}

preview(() => <DetailsScreen />);

For expo-router, set wrapWithNavigationContainer={false}:

<DevToolsProvider wrapWithNavigationContainer={false}>
  <Stack>
    {/* Your routes */}
  </Stack>
</DevToolsProvider>

Multiple Previews

Only one preview can be active at a time. If multiple preview() calls are detected, the app will show an error with all preview locations. Remove all but one preview() call.

API Reference

DevToolsProvider

Component-based provider for preview mode.

Props:

• children: Your app component(s)
• wrapWithNavigationContainer (optional, default: true): If true, wraps previews with NavigationContainer when @react-navigation/native is installed. Set to false for expo-router or if you're already wrapping with NavigationContainer.

Example:

<DevToolsProvider>
  <AppNavigator />
</DevToolsProvider>

// For expo-router
<DevToolsProvider wrapWithNavigationContainer={false}>
  <Stack>
    <Stack.Screen name="index" />
  </Stack>
</DevToolsProvider>

preview(componentOrFactory)

Registers a component for preview mode.

Parameters:

• componentOrFactory: A React element or a function that returns a React element

Example:

// With element
preview(<MyComponent title="Preview" />);

// With factory function (recommended for Fast Refresh)
preview(() => <MyComponent title="Preview" />);

Note: The factory function approach is recommended because it ensures the component is created fresh on each render, which works better with Fast Refresh.

Troubleshooting

Preview Not Showing

If your preview isn't showing:

1. Check that DevToolsProvider is wrapping your app
2. Verify the Metro config includes the plugin
3. Ensure preview() is called in a .tsx or .jsx file
4. Ensure you're running in development mode

"Invalid hook call" Error

If you see this error:

1. Ensure the Metro plugin is properly configured
2. Check that React is resolved from a single location (no duplicate React instances)

Multiple Previews Error

If you see a "Multiple previews detected" error, remove all preview() calls except one.

Important Notes

• Previews are automatically disabled in production builds
• Only one preview can be active at a time
• The library is fully compatible with Fast Refresh
• Previews work in .tsx and .jsx files only

License

ISC