react-native-config - React Native

Learn how to configure React Native CLI behavior, platform settings, and project-specific options using react-native.config.js.

Overview

The react-native.config.js file (formerly react-native.config.js) allows you to configure:

Native dependencies (autolinking)
Platform-specific settings
Asset directories
CLI plugin behavior

Configuration File

Create react-native.config.js in your project root:

react-native.config.js

module.exports = {
  project: {
    ios: {},
    android: {},
  },
  assets: [],
  dependencies: {},
  commands: [],
};

Project Configuration

iOS Settings

react-native.config.js

module.exports = {
  project: {
    ios: {
      // Path to Xcode project
      project: './ios/MyApp.xcodeproj',
      
      // Or path to workspace
      // workspace: './ios/MyApp.xcworkspace',
      
      // Specify scheme (optional)
      scheme: 'MyApp',
      
      // Custom Podfile path
      podfile: './ios/Podfile',
      
      // Pod install command
      // podInstallCommand: 'bundle exec pod install',
    },
  },
};

Android Settings

react-native.config.js

module.exports = {
  project: {
    android: {
      // Path to Android project
      sourceDir: './android',
      
      // Main application path
      appName: 'app',
      
      // Package name
      packageName: 'com.myapp',
      
      // Build variant (for flavors)
      unstable_reactLegacyComponentNames: [],
    },
  },
};

Asset Management

Custom Asset Directories

react-native.config.js

module.exports = {
  assets: ['./assets/fonts/', './assets/images/'],
};

This tells React Native to link assets from these directories during builds.

Font Linking

react-native.config.js

module.exports = {
  assets: ['./assets/fonts/'],
};

Run to link fonts:

npx react-native-asset

Dependency Configuration

Configure autolinking behavior for native dependencies.

Disable Autolinking for Specific Package

react-native.config.js

module.exports = {
  dependencies: {
    'react-native-some-package': {
      platforms: {
        android: null, // Disable on Android
        ios: null,     // Disable on iOS
      },
    },
  },
};

Custom Linking Configuration

react-native.config.js

module.exports = {
  dependencies: {
    'some-library': {
      platforms: {
        ios: {
          project: 'SomeLibrary.xcodeproj',
          sharedLibraries: ['libz', 'libsqlite3'],
        },
        android: {
          sourceDir: '../node_modules/some-library/android',
          packageImportPath: 'import com.somelibrary.SomeLibraryPackage;',
        },
      },
    },
  },
};

Exclude Dependencies

react-native.config.js

module.exports = {
  dependencies: {
    'react-native-excluded': {
      platforms: {
        android: null,
        ios: null,
      },
    },
  },
};

Custom Commands

Add custom CLI commands:

react-native.config.js

module.exports = {
  commands: [
    {
      name: 'my-command',
      func: (argv, config, args) => {
        console.log('Running custom command');
        // Command implementation
      },
      description: 'Description of my command',
      options: [
        {
          name: '--option <value>',
          description: 'Description of option',
        },
      ],
    },
  ],
};

Run:

npx react-native my-command --option value

Platform-Specific Configurations

iOS Pod Configuration

react-native.config.js

module.exports = {
  project: {
    ios: {
      sourceDir: './ios',
      podfile: './ios/Podfile',
      // Use custom pod install command
      podInstallCommand: 'cd ios && bundle exec pod install',
    },
  },
};

Android Gradle Configuration

react-native.config.js

module.exports = {
  project: {
    android: {
      sourceDir: './android',
      manifestPath: './android/app/src/main/AndroidManifest.xml',
      packageName: 'com.myapp',
    },
  },
};

Common Use Cases

Monorepo Setup

react-native.config.js

const path = require('path');

module.exports = {
  project: {
    ios: {
      project: './ios/MyApp.xcodeproj',
    },
    android: {
      sourceDir: './android',
    },
  },
  dependencies: {
    '@workspace/shared-ui': {
      root: path.join(__dirname, '../../packages/shared-ui'),
    },
  },
};

Custom Asset Paths

react-native.config.js

module.exports = {
  assets: [
    './src/assets/fonts/',
    './src/assets/images/',
    './common/assets/',
  ],
};

Multiple App Variants

react-native.config.js

module.exports = {
  project: {
    ios: {
      scheme: process.env.VARIANT === 'staging' ? 'MyApp-Staging' : 'MyApp',
    },
    android: {
      sourceDir: './android',
      appName: process.env.VARIANT === 'staging' ? 'app-staging' : 'app',
    },
  },
};

Disable Flipper

react-native.config.js

module.exports = {
  dependencies: {
    'react-native-flipper': {
      platforms: {
        ios: null,
        android: null,
      },
    },
  },
};

Autolinking

How Autolinking Works

React Native CLI automatically links native dependencies based on:

Package’s react-native.config.js
Your project’s react-native.config.js
Convention-based discovery

View Autolinking Config

npx react-native config

Shows resolved configuration including all dependencies.

Debug Autolinking

npx react-native config --verbose

Library Configuration

If you’re building a React Native library, configure it for autolinking:

react-native.config.js

module.exports = {
  dependency: {
    platforms: {
      ios: {
        project: './ios/MyLibrary.xcodeproj',
        sharedLibraries: ['libz'],
      },
      android: {
        sourceDir: './android',
        packageImportPath: 'import com.mylibrary.MyLibraryPackage;',
        packageInstance: 'new MyLibraryPackage()',
      },
    },
    assets: ['./assets/'],
    hooks: {
      postlink: 'node scripts/postlink.js',
    },
  },
};

Environment-Specific Config

react-native.config.js

const isDevelopment = process.env.NODE_ENV === 'development';
const isStaging = process.env.VARIANT === 'staging';

module.exports = {
  project: {
    ios: {
      scheme: isStaging ? 'MyApp-Staging' : 'MyApp',
    },
  },
  dependencies: {
    'react-native-flipper': {
      platforms: {
        ios: isDevelopment ? {} : null,
        android: isDevelopment ? {} : null,
      },
    },
  },
};

Reactotron Configuration

Integrate Reactotron with custom config:

react-native.config.js

module.exports = {
  dependencies: {
    'reactotron-react-native': {
      platforms: {
        ios: process.env.NODE_ENV === 'development' ? {} : null,
        android: process.env.NODE_ENV === 'development' ? {} : null,
      },
    },
  },
};

Troubleshooting

Dependency Not Linking

Solution:

Check config:

npx react-native config

Verify dependency has proper config
Try manual linking if needed

Assets Not Found

Solution:

react-native.config.js

module.exports = {
  assets: ['./assets/fonts/'],
};

Then run:

npx react-native-asset

CocoaPods Issues

Solution:

react-native.config.js

module.exports = {
  project: {
    ios: {
      podInstallCommand: 'cd ios && pod install',
    },
  },
};

Gradle Build Fails

Solution: Ensure Android config points to correct paths:

module.exports = {
  project: {
    android: {
      sourceDir: './android',
      appName: 'app',
    },
  },
};

Migration from Old Config

If you have old rn-cli.config.js:

Old Format

rn-cli.config.js

module.exports = {
  getProjectRoots() {
    return [path.resolve(__dirname)];
  },
  getAssetExts() {
    return ['png', 'jpg'];
  },
};

New Format

react-native.config.js

module.exports = {
  assets: ['./assets/'],
};

Metro config moved to metro.config.js.

Best Practices

Keep Config Minimal

Only include necessary configuration. React Native’s defaults work for most cases.

Document Custom Settings

Add comments explaining why custom configuration is needed:

module.exports = {
  // Disable autolinking for manual control
  dependencies: {
    'react-native-some-lib': {
      platforms: { ios: null, android: null }
    }
  }
};

Use Environment Variables

Make config environment-aware:

const isProduction = process.env.NODE_ENV === 'production';

Version Control

Commit react-native.config.js to version control.

Metro Config

For bundler configuration, use metro.config.js:

metro.config.js

const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
module.exports = mergeConfig(getDefaultConfig(__dirname), {});

Babel Config

For JavaScript transformation, use babel.config.js:

babel.config.js

module.exports = {
  presets: ['module:@react-native/babel-preset'],
};

TypeScript Config

For TypeScript, use tsconfig.json:

tsconfig.json

{
  "extends": "@react-native/typescript-config/tsconfig.json"
}

CLI Commands Reference

View Config

npx react-native config

Doctor (Check Setup)

npx react-native doctor

Info (Environment Info)

npx react-native info

Advanced Configuration

Custom Plugin

react-native.config.js

module.exports = {
  commands: require('./commands'),
  platforms: {
    windows: {
      npmPackageName: 'react-native-windows',
      projectConfig: require('./windows/projectConfig'),
      dependencyConfig: require('./windows/dependencyConfig'),
    },
  },
};

Hooks

react-native.config.js

module.exports = {
  dependency: {
    hooks: {
      postlink: 'node scripts/postlink.js',
      postunlink: 'node scripts/postunlink.js',
    },
  },
};

Next Steps

Metro Config

Configure Metro bundler

CLI Overview

All available CLI commands

Native Modules

Build native modules

Autolinking

Understanding autolinking

​Overview

​Configuration File

​Project Configuration

​iOS Settings

​Android Settings

​Asset Management

​Custom Asset Directories

​Font Linking

​Dependency Configuration

​Disable Autolinking for Specific Package

​Custom Linking Configuration

​Exclude Dependencies

​Custom Commands

​Platform-Specific Configurations

​iOS Pod Configuration

​Android Gradle Configuration

​Common Use Cases

​Monorepo Setup

​Custom Asset Paths

​Multiple App Variants

​Disable Flipper

​Autolinking

​How Autolinking Works

​View Autolinking Config

​Debug Autolinking

​Library Configuration

​Environment-Specific Config

​Reactotron Configuration

​Troubleshooting

​Dependency Not Linking

​Assets Not Found

​CocoaPods Issues

​Gradle Build Fails

​Migration from Old Config

​Old Format

​New Format

​Best Practices

​Related Configuration

​Metro Config

​Babel Config

​TypeScript Config

​CLI Commands Reference

​View Config

​Doctor (Check Setup)

​Info (Environment Info)

​Advanced Configuration

​Custom Plugin

​Hooks

​Next Steps

Metro Config

CLI Overview

Native Modules

Autolinking

Overview

Configuration File

Project Configuration

iOS Settings

Android Settings

Asset Management

Custom Asset Directories

Font Linking

Dependency Configuration

Disable Autolinking for Specific Package

Custom Linking Configuration

Exclude Dependencies

Custom Commands

Platform-Specific Configurations

iOS Pod Configuration

Android Gradle Configuration

Common Use Cases

Monorepo Setup

Custom Asset Paths

Multiple App Variants

Disable Flipper

Autolinking

How Autolinking Works

View Autolinking Config

Debug Autolinking

Library Configuration

Environment-Specific Config

Reactotron Configuration

Troubleshooting

Dependency Not Linking

Assets Not Found

CocoaPods Issues

Gradle Build Fails

Migration from Old Config

Old Format

New Format

Best Practices

Related Configuration

Metro Config

Babel Config

TypeScript Config

CLI Commands Reference

View Config

Doctor (Check Setup)

Info (Environment Info)

Advanced Configuration

Custom Plugin

Hooks

Next Steps