Skip to main content
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:
  1. Package’s react-native.config.js
  2. Your project’s react-native.config.js
  3. 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:
  1. Check config:
npx react-native config
  1. Verify dependency has proper config
  2. 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

Only include necessary configuration. React Native’s defaults work for most cases.
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 }
    }
  }
};
Make config environment-aware:
const isProduction = process.env.NODE_ENV === 'production';
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

Build docs developers (and LLMs) love

Get started for freeTalk to us