Fixing React Native Path Alias Error: Unable to Resolve Module @/app/App

The Problem

If you're using path aliases (like @/) in your React Native project, you might encounter this frustrating error:

ERROR  Error: Unable to resolve module @/app/App from /path/to/project/index.ts: 
@/app/App could not be found within the project or in these directories:
  node_modules
  ../node_modules

This happens even when your TypeScript configuration is correct and your IDE shows no errors. What's going on?

Why This Happens

The issue occurs because TypeScript and Metro (React Native's bundler) are two separate systems:

• TypeScript understands your path aliases through tsconfig.json
• Metro (the bundler) has no idea about these aliases unless you explicitly configure it

Your IDE might show everything is fine because it uses TypeScript for type checking, but when you actually run the app, Metro tries to bundle the code and can't resolve the @ alias.

The Solution

Step 1: Install babel-plugin-module-resolver

npm install --save-dev babel-plugin-module-resolver

Step 2: Update babel.config.js

Add the module-resolver plugin to your Babel configuration:

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

Step 3: Clear Cache and Restart

This is crucial! Metro caches the bundled files, so you need to clear it:

1. Kill any running Metro bundler process (Ctrl+C)
2. Clear the cache:

   npx react-native start --reset-cache

3. In another terminal, rebuild your app:

   npm run android
   # or
   npm run ios

Understanding the Configuration

Let's break down what we added to babel.config.js:

• root: ['./'] - Tells the plugin where to start resolving paths from (project root)
• alias: { '@': './' } - Maps the @ symbol to your project root directory

Now when Metro encounters @/app/App, it knows to look for ./app/App from your project root.

Common Variations

You can configure multiple aliases if needed:

alias: {
  '@': './',
  '@components': './src/components',
  '@utils': './src/utils',
  '@screens': './src/screens',
}

Pro Tips

• Always restart with cache cleared after changing Babel config
• Keep TypeScript and Babel aliases in sync to avoid confusion
• Document your aliases in your project README for team members

Conclusion

Path aliases make your imports cleaner and your code more maintainable, but they require proper configuration in React Native. By using babel-plugin-module-resolver, you bridge the gap between TypeScript's understanding of paths and Metro's bundling process.

Remember: TypeScript config is for type checking, Babel config is for runtime/bundling. Keep both aligned!

❤️ Support This Blog

---

If this post helped you, you can support my writing with a small donation. Thank you for reading.

---

Coffee ☕ Thanks 🙏 Extra Support ❤️