In a React Native CRM app, an @components alias passes tsc but Metro says 'Unable to resolve module'; why, and what fixes it?

## The symptom A CRM app's team wants shorter imports. Someone adds this to `tsconfig.json`: ```json { "extends": "@react-native/typescript-config", "compilerOptions": { "paths": { "@components/*": ["./src/components/*"] } } } ``` and changes `import ContactCard from '../../../components/ContactCard'` to `import ContactCard from '@components/ContactCard'`. The editor is happy, `npx tsc` passes, and the app fails to load: Metro reports **Unable to resolve module @components/ContactCard**. ## Why it type-checks A **path alias** in `tsconfig.json` tells the TypeScript compiler where to look when it sees an import that matches the pattern. It affects **type resolution only**. TypeScript does not rewrite import specifiers in its output, and in a React Native app it produces no output anyway: the base config sets `noEmit: true`. ## Why it fails at runtime **Metro** builds the bundle. It transforms each file with **Babel** and then resolves every import itself. Neither Babel's default React Native preset nor Metro reads `tsconfig.json`. To Metro, `@components/ContactCard` looks like a scoped npm package named `@components`, which does not exist in `node_modules`, so resolution fails. The general rule: **every resolution trick has to be taught to both tools**, because they resolve independently. ## The documented fix The React Native TypeScript docs describe three steps: 1. Declare the alias in `tsconfig.json` `paths`, as above. 2. Install **`babel-plugin-module-resolver`** as a dev dependency. 3. Configure it in `babel.config.js` with the same mapping. The plugin rewrites `@components/ContactCard` into a relative path during Babel's transform, before Metro resolves it, so Metro sees an ordinary relative import. One trap in the docs: their example still lists the old `module:metro-react-native-babel-preset`. Current apps use **`module:@react-native/babel-preset`**; keep whatever preset your template ships and only add the plugin. ## Why the fix seems not to work After editing `babel.config.js`, many teams still see the same error. Metro caches transformed files, and React Native's Babel transformer builds its cache key from the preset and the transformer itself, **not** from your project's Babel config. Old transform results stay valid in Metro's eyes. Restart the dev server with a clean cache: - `npx react-native start --reset-cache`, or the equivalent `npm start -- --reset-cache`. ## Keeping the two mappings honest | Check | Why | |---|---| | Same alias names in both files | a typo in one gives type-only or runtime-only failures | | Same target folders | otherwise types come from one file and code from another | | Jest uses the same Babel config | tests then resolve aliases the way the app does | | One owner for both files | alias changes land in one reviewed commit | Two further points: - An alias that points at the wrong folder in Babel but the right one in `tsconfig.json` is the worst case: types check against one file while the bundle loads another. - Metro can also be taught aliases through its own resolver configuration, which is a Metro configuration topic; the Babel plugin is the route the React Native docs document. ## The lesson In React Native, `tsconfig.json` describes the program to the type checker, while `babel.config.js` and Metro describe it to the bundle. A green `tsc` run proves nothing about whether Metro can resolve an import. ## Diagnosing which half is broken When an alias misbehaves, test each resolver separately: - **`tsc` fails, the app runs**: the Babel mapping exists but `paths` is missing or wrong; the editor also loses types for the import. - **`tsc` passes, Metro fails**: the classic case above; the Babel plugin is missing, misconfigured, or Metro is serving stale transforms. - **Both pass, wrong behaviour**: the two mappings point at different folders; compare them line by line. - **Tests fail, app runs**: Jest is not picking up the same Babel configuration or has its own module mapping that disagrees. Fixing the right half first saves the usual cycle of editing both files at random and restarting Metro between attempts.