Hey everyone! 👋
Recently, I ran into several path-alias resolution errors in a React Native project built with Expo.
The configuration I had set up months earlier in my tsconfig.json and babel.config.js files was no longer working consistently. Imports that previously seemed fine were causing problems during the bundling process.
After investigating the issue, I discovered that there were multiple problems involving TypeScript, Babel, Metro, and even a missing dependency.
In this article, I'll walk through the changes I made, explain why they were necessary, and share a few lessons learned along the way.
Table of Contents
- 1. The original configuration
- 2. Removing
baseUrl - 3. Using wildcards correctly in TypeScript and Babel
- 4. Configuring TypeScript and React Native extensions in Babel
- 5. Standardizing imports
- 6. Fixing TypeScript's
includeconfiguration - 7. Aligning NativeWind CSS imports with Metro
- 8. Another issue: Metro stuck at
0/1 - 9. Do Expo projects still need babel-plugin-module-resolver?
- 10. Final thoughts
- References
1. The original configuration
Before making any changes, my tsconfig.json contained the following path aliases:
{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["*"], "@/components/*": ["components/*"], "@/contexts/*": ["contexts/*"], "@/screens/*": ["screens/*"], "@/services/*": ["services/*"], "@/utils/*": ["utils/*"], "@/validators/*": ["validators/*"], "@/assets/*": ["assets/*"] } } } And my babel.config.js included this configuration for babel-plugin-module-resolver:
{ root: ["."], alias: { "@": "./", "@/components": "./components", "@/contexts": "./contexts", "@/screens": "./screens", "@/validators": "./validators", "@/assets": "./assets", "@/services": "./services", "@/utils": "./utils", }, } At first glance, everything seemed correct. However, the aliases were not being resolved as expected during the transformation process.
So, I started reviewing each configuration separately.
2. Removing baseUrl
The first change was related to the baseUrl option.
According to the TypeScript 6.0 release notes, this option has been deprecated, and its old module-resolution behavior will no longer be supported in TypeScript 7.0.
Since TypeScript 4.1, baseUrl has not been required when using paths.
Previously, I had:
{ "compilerOptions": { "baseUrl": ".", "paths": { "@/components/*": ["components/*"] } } } After removing baseUrl, I updated the path mappings to use explicitly relative destinations:
{ "compilerOptions": { "paths": { "@components/*": ["./components/*"] } } } This makes the path mappings independent of baseUrl and prepares the configuration for newer TypeScript versions.
Important: Removing baseUrl was not the main fix for the runtime error. It was a necessary configuration improvement, but the actual alias-resolution issue was related to how the mappings were handled.
3. Using wildcards correctly in TypeScript and Babel
The next issue involved the differences between TypeScript path mappings and Babel aliases.
TypeScript supports wildcard patterns such as:
{ "compilerOptions": { "paths": { "@components/*": ["./components/*"], "@contexts/*": ["./contexts/*"], "@screens/*": ["./screens/*"], "@services/*": ["./services/*"], "@utils/*": ["./utils/*"] } } } However, the configuration I needed for babel-plugin-module-resolver used simple alias names instead of TypeScript-style wildcard mappings:
alias: { "@components": "./components", "@contexts": "./contexts", "@screens": "./screens", "@services": "./services", "@utils": "./utils", } The key point is that TypeScript and Babel don't use exactly the same alias configuration syntax.
During debugging, I noticed that Babel was leaving some imports unchanged:
import Button from "@components/UI/Button"; After updating the Babel configuration, the plugin was able to transform these imports into resolvable relative paths.
Although babel-plugin-module-resolver also supports more advanced mappings using regular expressions, simple aliases were sufficient for my project.
You can find more examples in the official babel-plugin-module-resolver repository.
4. Configuring TypeScript and React Native extensions in Babel
Another adjustment involved explicitly defining the file extensions that Babel should consider when resolving imports.
Since React Native projects can use platform-specific files, such as .ios.tsx and .android.tsx, I added the following extensions:
extensions: [ ".ios.ts", ".android.ts", ".ts", ".ios.tsx", ".android.tsx", ".tsx", ".jsx", ".js", ".json", ], This allows the resolver to look for TypeScript, JavaScript, JSON, and platform-specific files.
After these changes, my complete babel.config.js looked like this:
module.exports = function (api) { api.cache(true); return { presets: [ [ "babel-preset-expo", { jsxImportSource: "nativewind" }, ], "nativewind/babel", ], plugins: [ [ "module-resolver", { root: ["."], extensions: [ ".ios.ts", ".android.ts", ".ts", ".ios.tsx", ".android.tsx", ".tsx", ".jsx", ".js", ".json", ], alias: { "@app": "./app", "@assets": "./assets", "@components": "./components", "@contexts": "./contexts", "@hooks": "./hooks", "@mappers": "./mappers", "@repositories": "./repositories", "@screens": "./screens", "@services": "./services", "@styles": "./styles", "@utils": "./utils", "@validators": "./validators", }, }, ], ], }; }; The NativeWind configuration was already part of my project, so I kept it while updating the module resolver.
One thing worth mentioning is that the extension list and the Babel configuration should be adapted to the actual dependencies and project structure.
5. Standardizing imports
Once the aliases were correctly configured, I also standardized the imports throughout the application.
Previously, I was using:
// Old imports import Button from "@/components/UI/Button"; import { useAuth } from "@/contexts/AuthContext"; I replaced them with:
// Updated imports import Button from "@components/UI/Button"; import { useAuth } from "@contexts/AuthContext"; This approach makes the imports more explicit and provides a consistent naming convention across the project.
It also avoids relying on a generic @ alias for every directory.
The important thing is to ensure that the alias names used in the source code match the mappings defined in the configuration files.
6. Fixing TypeScript's include configuration
While checking the TypeScript configuration, I noticed another issue.
My tsconfig.json was only including declaration files:
{ "include": [ "env.d.ts", "nativewind-env.d.ts" ] } As a result, running:
npx tsc --noEmit could finish successfully without checking the application's .ts and .tsx source files.
This was particularly misleading because a successful TypeScript check didn't necessarily mean the application was correctly configured.
To fix it, I updated the include section:
{ "include": [ "**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "env.d.ts", "nativewind-env.d.ts" ] } Now, TypeScript can validate the application source files rather than checking only the declarations.
This change doesn't directly fix runtime alias resolution, but it makes the type-checking process much more reliable.
7. Aligning NativeWind CSS imports with Metro
After fixing the aliases, I also needed to review the NativeWind configuration.
The global stylesheet had been moved to:
styles/global.css However, the Metro configuration and the application imports still needed to reference the correct location.
I updated the import:
import "@styles/global.css"; And configured Metro to use the same file:
module.exports = withNativeWind(config, { input: "./styles/global.css", }); This ensured that the stylesheet location was consistent across the application and the NativeWind configuration.
Without this adjustment, Metro was getting stuck at the beginning of the transformation process.
At this point, I expected everything to work correctly.
But there was still another problem. 😅
8. Another issue: Metro stuck at 0/1
Even after fixing the aliases and the stylesheet configuration, Metro was still getting stuck at 0/1 during bundling.
Initially, I thought this was another alias-resolution issue.
However, after further investigation, I discovered that the problem was related to a missing dependency.
The version of react-native-reanimated used in my project required react-native-worklets, which was not installed.
The solution was:
npx expo install react-native-worklets After installing the dependency, I restarted Expo and cleared the Metro cache:
npx expo start --clear This resolved the additional bundling issue in my environment.
It is important to distinguish these two problems: the alias configuration and the missing Worklets dependency were separate issues that happened to produce similar symptoms during development.
For more information, see the React Native Reanimated installation documentation.
9. Do Expo projects still need babel-plugin-module-resolver?
One interesting thing I learned while reviewing the documentation is that modern Expo projects already support TypeScript path aliases automatically.
According to the Expo TypeScript documentation, Expo CLI can resolve aliases defined in compilerOptions.paths.
For example:
{ "extends": "expo/tsconfig.base", "compilerOptions": { "strict": true, "paths": { "@components/*": ["./components/*"], "@contexts/*": ["./contexts/*"], "@screens/*": ["./screens/*"] } }, "include": [ "**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts" ] } This means that, for many Expo projects, a separate Babel module resolver may not be necessary.
In my case, I corrected the existing Babel setup while investigating the issue. However, if I were configuring a new Expo project today, I would first consider using Expo's built-in path-alias support to avoid unnecessary configuration duplication.
It's also worth remembering that TypeScript path aliases don't automatically configure every tool in the development environment. Depending on your setup, additional tools may require their own configuration.
10. Final thoughts
What initially seemed like a simple import-path problem turned into a broader review of my project's configuration.
The main changes included removing the deprecated baseUrl option, correcting alias mappings in TypeScript and Babel, defining appropriate file extensions, standardizing imports, expanding TypeScript's source-file coverage, and aligning the NativeWind stylesheet path with Metro.
I also discovered an unrelated dependency issue involving React Native Reanimated and Worklets.
The biggest lesson from this experience is that not every bundling error is caused by the first configuration file that appears suspicious.
TypeScript, Babel, Metro, and native dependencies play different roles in a React Native application. A configuration that works for type checking does not necessarily guarantee successful bundling or runtime execution.
If you're facing similar issues, I recommend checking each part of the toolchain independently instead of changing multiple configurations without verifying the results.
Sometimes the problem isn't just the aliases. It's the interaction between the tools responsible for resolving them.
Hope this helps someone dealing with the same problem!
Happy coding! 🚀
