Why RN-Restart?

Sometimes your React Native app needs a fresh start. Whether you're applying language changes, switching themes, implementing OTA updates, or recovering from errors – RN-Restart provides a simple, reliable way to restart your app programmatically.

Built with modern React Native architecture (Turbo Modules) for optimal performance and future compatibility.

✨ Features

📋 Table of Contents

• Installation
• Compatibility
• Usage
  • Basic Restart
  • Restart with Cache Clear
  • Real-World Examples
• API Reference
• Platform Differences
• Use Cases
• Troubleshooting
• Contributing
• License

📦 Installation

Step 1: Install the package

npm install rn-restart

or with yarn:

yarn add rn-restart

Step 2: Platform setup

iOS

cd ios && pod install

Android
✅ Auto-linked! No additional setup needed.

🔧 Compatibility

| Platform | Minimum Version | Status | |:--------:|:---------------:|:------:| | React Native | 0.70+ | ✅ | | iOS | 13.0+ | ✅ | | Android | API 21+ | ✅ | | Node.js | 18+ | ✅ |

🚀 Quick Start

Basic Usage

import { restart, restartWithCacheClear } from 'rn-restart';

// Simple restart
restart();

// Restart with cache clearing (great for Android)
restartWithCacheClear();

That's it! Just call the function when you need to restart. ⚡

import React from 'react';
import { View, Button, Alert } from 'react-native';
import { restart } from 'rn-restart';

export default function SettingsScreen() {
  const handleRestart = () => {
    Alert.alert(
      'Restart App',
      'Are you sure you want to restart?',
      [
        { text: 'Cancel', style: 'cancel' },
        { text: 'Restart', onPress: () => restart() }
      ]
    );
  };

  return (
    <View>
      <Button title="Restart App" onPress={handleRestart} />
    </View>
  );
}

💼 Real-World Use Cases

🌍 1. Language/Locale Change

import { restart } from 'rn-restart';
import AsyncStorage from '@react-native-async-storage/async-storage';
import i18n from 'i18next';

const changeLanguage = async (languageCode: string) => {
  try {
    // Save the new language preference
    await AsyncStorage.setItem('userLanguage', languageCode);
    
    // Update i18n
    await i18n.changeLanguage(languageCode);
    
    // Restart to apply changes throughout the app
    restart();
  } catch (error) {
    console.error('Failed to change language:', error);
  }
};

🎨 2. Theme Switching

import { restart } from 'rn-restart';
import { Alert } from 'react-native';

const switchTheme = async (theme: 'light' | 'dark') => {
  Alert.alert(
    'Restart Required',
    'The app needs to restart to apply the new theme. Continue?',
    [
      { text: 'Cancel', style: 'cancel' },
      {
        text: 'Restart',
        onPress: async () => {
          await AsyncStorage.setItem('theme', theme);
          restart();
        },
      },
    ]
  );
};

📦 3. After OTA Updates

import { restartWithCacheClear } from 'rn-restart';
import codePush from 'react-native-code-push';

const checkForUpdates = async () => {
  const update = await codePush.checkForUpdate();
  
  if (update) {
    await update.download();
    await update.install(codePush.InstallMode.IMMEDIATE);
    
    // Restart with cache clear to ensure clean update
    restartWithCacheClear();
  }
};

🔐 4. User Logout

import { restartWithCacheClear } from 'rn-restart';

const logout = async () => {
  try {
    // Clear user data
    await AsyncStorage.clear();
    
    // Clear any cached tokens
    await clearAuthTokens();
    
    // Restart with cache clear for complete cleanup
    restartWithCacheClear();
  } catch (error) {
    console.error('Logout failed:', error);
  }
};

🐛 5. Error Recovery

import { restart } from 'rn-restart';
import { ErrorBoundary } from 'react-error-boundary';

const ErrorFallback = ({ error, resetErrorBoundary }) => (
  <View style={styles.container}>
    <Text style={styles.title}>Something went wrong</Text>
    <Text style={styles.error}>{error.message}</Text>
    <Button
      title="Restart App"
      onPress={() => {
        resetErrorBoundary();
        restart();
      }}
    />
  </View>
);

const App = () => (
  <ErrorBoundary FallbackComponent={ErrorFallback}>
    <YourApp />
  </ErrorBoundary>
);

📚 API Reference

restart()

Restarts the React Native application by reloading the JavaScript bundle.

Platform Support: iOS, Android

Returns: void

Example:

import { restart } from 'rn-restart';

restart();

What it does:

• iOS: Triggers RCTReloadCommand to reload the React Native bridge
• Android: Restarts the main activity with cleared task flags

restartWithCacheClear()

Restarts the React Native application after clearing cached data.

Platform Support: iOS (network cache only), Android (full app cache)

Returns: void

Example:

import { restartWithCacheClear } from 'rn-restart';

restartWithCacheClear();

What it does:

• iOS: Clears NSURLCache and reloads the React Native bridge
• Android: Recursively deletes the app's cache directory, then restarts

🔀 Platform Differences

⚠️ Important Notes

✅ Perfect For

Language changes • Theme switching • OTA updates • User logout • Error recovery • Config updates

❌ Not For

Navigation resets • State resets • Frequent operations • Background tasks

🆘 Troubleshooting

App doesn't restart on iOS

Solution: Ensure your app is using the new architecture with Turbo Modules enabled.

# ios/Podfile
use_react_native!(
  :path => config[:reactNativePath],
  :hermes_enabled => true,
  :fabric_enabled => true # Enable new architecture
)

Android app crashes on restart

Solution: Make sure your MainActivity is properly configured:

// MainActivity.kt
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(null) // Pass null to prevent state restoration
}

Cache not clearing on Android

Solution: Verify your app has proper permissions. The module uses the app's cache directory which doesn't require special permissions, but ensure you're not blocking file operations.

TypeScript types not found

Solution: Ensure your TypeScript configuration includes the module:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "resolveJsonModule": true
  }
}

🎨 Example App

This repository includes a beautiful example app showcasing all features:

git clone https://github.com/abdallaemadeldin/RN-Restart.git
cd RN-Restart
yarn
yarn example ios    # or: yarn example android

What's included:

• ✅ Standard restart with confirmation
• ✅ Restart with cache clearing
• ✅ Delayed restart with countdown
• ✅ Platform-specific behavior demos
• ✅ Real-world use case examples
• ✅ Modern, beautiful UI

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

🐛 Found a Bug?

Report it

💡 Have an Idea?

Request a Feature

💬 Questions?

Start a Discussion

📄 License

MIT © Abdalla Emad Eldin

⭐ Star this repo if you find it useful!

📚 More Resources

API Documentation • Changelog • Quick Start Guide

Built with ❤️ for the React Native community

Made with create-react-native-library