Why This Matters: Beyond the Basics

Alright, let’s talk about setting up a React Native project. Specifically, we’re diving deep into the React Native CLI setup with TypeScript and absolute paths. If you’ve been around the block, you know that getting your project structure, build tools, and type safety dialed in from the start is *crucial*. It’s the foundation upon which you’ll build everything else, and a shaky foundation? Well, that’s just asking for a world of pain down the line. We’re talking about things that will slow down your development, introduce hard-to-debug errors, and generally make your life miserable. This isn’t just about getting a project to run; it’s about setting up a robust, scalable, and maintainable codebase from day one. Especially in 2026, where expectations for mobile app quality and developer experience are higher than ever.

Many developers, especially those new to the ecosystem or coming from less opinionated frameworks, might gloss over this initial setup. They might stick with relative imports, put off TypeScript, or just accept the default project structure. But trust me, from years of wrestling with React Native projects of all sizes, spending a little extra time upfront to get this right pays dividends. This article is for those mid-to-senior level developers who understand the fundamentals but want practical, real-world insights on how to avoid the common traps and build a solid React Native CLI setup with TypeScript and absolute paths.

The “New Project” Experience: What You Get Out of the Box

When you first run npx react-native init MyAwesomeApp (or whatever your project name is), the React Native CLI does a decent job of giving you a starting point. You get a basic project structure: android/ and ios/ for native code, src/ (or sometimes just the root) for your JavaScript/TypeScript code, and essential configuration files like package.json and metro.config.js.

Out of the box, it’s usually JavaScript. You’ll see a lot of .js and .jsx files. Imports will be relative, like ../../components/Button. This works fine for small projects. But as your codebase grows, navigating these deeply nested relative paths becomes a nightmare. Imagine having to trace ../../../../../shared/ui/components/Modal. It’s not just tedious; it’s error-prone. You might accidentally import the wrong thing, and debugging those kinds of mistakes is a time sink.

The default setup is good for a quick start, but it’s not optimized for long-term maintainability or leveraging modern JavaScript/TypeScript features effectively. That’s where we come in to improve it.

Introducing TypeScript: The Modern Standard

If you’re not already using TypeScript in your React Native projects, you’re leaving a lot on the table. For me, TypeScript is non-negotiable in any serious project. It’s not just about type checking, although that’s a massive win. It’s about:

• Early Error Detection: Catching typos, incorrect function arguments, or undefined variables *before* you even run your app. This saves countless hours of debugging.
• Improved Readability and Maintainability: Explicit types make your code’s intent clearer. When you or another developer comes back to a module months later, it’s much easier to understand what’s going on.
• Better Developer Experience (DX): Autocompletion, intelligent suggestions, and refactoring tools powered by type information are invaluable. IDEs become significantly more powerful.
• Facilitating Collaboration: When multiple developers are working on a project, TypeScript acts as a contract, ensuring everyone is on the same page about data structures and function signatures.

Adding TypeScript to an existing JavaScript project can be a task, but when you’re starting fresh with the React Native CLI setup, it’s a no-brainer. You’ll want to ensure your tsconfig.json is configured correctly for React Native. A good starting point often looks something like this:


{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"jsx": "react-native",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"baseUrl": ".", // This is key for absolute paths
"paths": {}
},
"exclude": [
"node_modules",
"babel.config.js",
"metro.config.js",
"jest.config.js"
]
}


The "baseUrl": "." and "moduleResolution": "node" are standard. "jsx": "react-native" tells the compiler how to handle JSX. "strict": true enables a suite of helpful type-checking options. "skipLibCheck": true is often used to speed up compilation, though it has trade-offs if library typings are critical for your project.

Taming Imports: The Case for Absolute Paths

This is where things really start to shine. Relative imports, as I mentioned, are the default. import Button from '../../../components/common/Button';. This works, but it’s brittle and hard to read. If you move a component or its parent directory, you have to update all its relative imports. This is a maintenance nightmare.

Absolute paths, on the other hand, provide a stable reference point. Instead of importing from a path relative to the current file, you import from a path relative to your project’s root directory. So, instead of the above, you’d have something like:


import Button from '@src/components/common/Button';


This makes your imports:

• More Readable: You immediately know where the module is coming from in the project structure.
• More Maintainable: Moving files around has a much smaller impact on your imports.
• Less Error-Prone: Reduces the chances of importing the wrong module or creating circular dependencies unintentionally.

The convention of using a prefix like @src/ or @/ is common and highly recommended. It clearly delineates your application’s source code from external libraries. The @/ convention is particularly popular when using Webpack or similar bundlers, but @src/ is often clearer for React Native projects.

Setting Up Absolute Paths: The `tsconfig.json` Dance

To make absolute paths work with TypeScript, you need to configure the paths property in your tsconfig.json file. This tells the TypeScript compiler how to map these aliases to actual file system paths.

Let’s update our tsconfig.json to include our @src alias. Assuming your source code lives in a directory named src/ at the root of your project:


{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"jsx": "react-native",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"baseUrl": ".",
"paths": {
"@src/*": ["src/*"]
}
},
"exclude": [
"node_modules",
"babel.config.js",
"metro.config.js",
"jest.config.js"
]
}


Here’s what’s happening:

• `”baseUrl”: “.”`: This is crucial. It defines the base directory for resolving non-relative module references. In this case, it’s the project root.
• `”paths”: { “@src/*”: [“src/*”] }`: This is the magic. It says: “When you see an import starting with @src/, treat it as if it were relative to the src/ directory.” The * acts as a wildcard, matching any path segment after @src/ and mapping it to the same segment under src/.

So, an import like import MyComponent from '@src/components/MyComponent'; will be correctly resolved by TypeScript to ./src/components/MyComponent relative to the project root.

Leveraging the React Native CLI for TypeScript

The React Native CLI has good built-in support for TypeScript. When you initialize a project with TypeScript enabled (which you should!), it often sets up a reasonable default tsconfig.json and configures the Metro bundler to work with it. Metro, the JavaScript bundler for React Native, needs to understand how to process your TypeScript files.

The typical setup uses @babel/preset-typescript. Your babel.config.js should already have this configured if you started your project with the TypeScript template. It looks something like this:


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


The module:metro-react-native-babel-preset itself includes the necessary Babel plugins and presets for handling TypeScript. If you ever find yourself needing custom Babel plugins, you’d add them to the plugins array. For example, for `react-native-reanimated`:


module.exports = {
presets: ['module:metro-react-native-babel-preset'],
plugins: [
// ... other plugins
'react-native-reanimated/plugin',
],
};


Make sure to restart your Metro bundler (usually by pressing r in the terminal where Metro is running, or stopping and restarting the app) after any changes to Babel or Metro configuration.

Handling Absolute Paths in the CLI: Gotchas and Solutions

Now, here’s where it gets a bit tricky. While tsconfig.json handles TypeScript’s understanding of absolute paths, the Metro bundler (which React Native uses) also needs to know about these aliases. Fortunately, Metro is usually smart enough to pick up on the baseUrl and paths from your tsconfig.json if it’s located at the project root.

However, there can be edge cases. If your tsconfig.json is in a subdirectory, or if you have a more complex monorepo setup, you might need to explicitly configure Metro. The metro.config.js file is where you’d do this. You can use the resolver.alias option.

Let’s say for some reason Metro isn’t picking up your @src alias automatically. You’d modify your metro.config.js:


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

/**
* Metro configuration
* https://facebook.github.io/metro/docs/configuration
*
* @type {import('metro-config').MetroConfig}
*/
const config = {
transformer: {
getTransformOptions: async () => ({
transform: {
experimentalImportSupport: false,
inlineRequires: true,
},
}),
},
resolver: {
// Add your aliases here if Metro isn't picking them up from tsconfig.json
alias: {
'@src': './src',
// You might add other aliases here if needed
// '@components': './src/components',
},
},
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);


In this example, '@src': './src' explicitly tells Metro to resolve any import starting with @src to the ./src directory relative to the project root. This is a good fallback and a way to be explicit.

Common Mistake: Path Mismatch Between TSConfig and Metro. The most frequent issue I see is when the aliases defined in tsconfig.json don’t perfectly match what Metro expects, or if Metro isn’t configured to look for them at all. Always ensure your baseUrl in tsconfig.json is set correctly and that your metro.config.js is either picking it up implicitly or has the aliases explicitly defined. A quick check after changing these configurations is to run npx react-native start --reset-cache to ensure Metro is using the latest config.

Best Practices for Project Structure and Imports

A well-defined project structure is paramount for maintainability, especially when using absolute paths. With absolute paths, you’re less tied to a specific folder hierarchy, but that doesn’t mean you should be disorganized!

I generally recommend a structure like this for React Native projects:

• src/: The root for all your application source code. This is where your tsconfig.json‘s baseUrl will point.
• src/assets/: For static assets like images, fonts, etc.
• src/components/: Reusable UI components. You might further subdivide this into common/, shared/, or feature-specific component folders.
• src/screens/ or src/views/: Top-level components that represent different screens in your app.
• src/navigation/: Navigation setup (e.g., React Navigation config).
• src/services/: API calls, data fetching logic.
• src/utils/: Helper functions, general utilities.
• src/hooks/: Custom React hooks.
• src/types/ or src/models/: TypeScript type definitions, interfaces, enums.
• src/constants/: App-wide constants.

Using absolute paths like @src/components/Button makes it easy to reference components regardless of where you are in the src/ directory.

Alias Strategy: Beyond @src/, consider creating aliases for other major directories if your project becomes very large. For example:

• @components/*: If your components folder gets huge, aliasing it separately can be nice, though @src/components/* is usually sufficient.
• @hooks/*, @services/*, etc.

You’d add these to your tsconfig.json‘s paths and potentially metro.config.js resolver.alias:


// tsconfig.json
"paths": {
"@src/*": ["src/*"],
"@components/*": ["src/components/*"],
"@hooks/*": ["src/hooks/*"],
// ... other aliases
}


This level of organization is key for large teams and long-lived projects.

Common Pitfalls and How to Avoid Them

1. Case Sensitivity Issues

The paths in tsconfig.json and metro.config.js are file system paths. On case-sensitive file systems (like Linux), @src/components/Button is different from @src/Components/Button. TypeScript and Metro might resolve them differently or fail entirely. Solution: Be consistent with your casing. Use lowercase for directory names and follow a consistent casing convention (e.g., PascalCase for component files) for file names. Ensure your aliases in config files match exactly.

2. Circular Dependencies

While absolute paths make it *easier* to create circular dependencies, they don’t prevent them. If Module A imports Module B, and Module B imports Module A, you’ll run into runtime errors or build failures. Solution: Use linters (like ESLint with import plugins) to detect circular dependencies. Refactor your code to break these cycles, often by introducing a new module that both original modules can depend on.

3. Incorrect `baseUrl` or `paths` Configuration

This is the most common. If baseUrl is wrong, or the mapping in paths is off, your imports simply won’t resolve. Solution: Double-check your tsconfig.json. Ensure baseUrl points to the directory containing your source code (usually the project root if `src` is there). Ensure the mapping in paths is correct (e.g., "@src/*": ["src/*"]). Test with simple imports first.

4. Forgetting to Reset the Cache

When you change Babel or Metro configurations, the bundler often caches things. If your absolute path aliases aren’t working, the first thing to try is restarting Metro with the cache reset. Solution: Run npx react-native start --reset-cache or delete the cache manually (usually in /tmp/metro-cache or similar on macOS/Linux) and restart.

5. Not Configuring for Jest

If you’re using Jest for testing, it also needs to understand your module aliases. By default, Jest might not. Solution: You’ll likely need to configure Jest to use `babel-jest` and tell it about your aliases. This often involves setting up a jest.config.js file. You might need to add:


// jest.config.js
module.exports = {
preset: 'react-native',
setupFilesAfterEnv: ['./jest-setup.js'], // Optional: for extra setup
moduleNameMapper: {
'^@src/(.*)$': '/src/$1',
// Add other aliases here if you have them
},
transformIgnorePatterns: [
'node_modules/(?!(react-native|@react-native|@react-navigation))',
],
};


The moduleNameMapper directly maps your aliases to their actual paths relative to the Jest root directory (``).

When Things Get Complex: Monorepos and Beyond

The patterns discussed here are foundational. When you step into monorepo territory (using tools like Yarn Workspaces, Lerna, or Nx), managing absolute paths and TypeScript becomes even more critical, but also more complex. Each package within a monorepo might have its own tsconfig.json, and you need a way to map aliases across packages.

In a monorepo, your tsconfig.json at the root will often set up a base configuration, and then individual packages extend this. Aliases need to be configured both in the root (for general project structure) and potentially within each package’s tsconfig.json or handled by the monorepo tooling itself. For example, if you have a shared UI library package in your monorepo, you might alias it like @my-org/ui.

Tools like Nx are fantastic for managing this complexity. They often provide built-in generators and configurations for setting up TypeScript and aliases correctly across your entire monorepo. The principles remain the same: define your aliases clearly in your compiler/bundler configurations.

What Didn’t Work (and Why)

Early on, I remember trying to hack absolute paths by manipulating Node.js’s module.paths or using complex regex in Babel plugins. It was a mess. These approaches were brittle, hard to debug, and quickly broke with React Native updates or changes in tooling. The key lesson learned was to stick to the established configuration patterns provided by TypeScript and Metro. They are designed to handle these scenarios robustly. Relying on these standard configurations ensures better compatibility and easier maintenance.

Another past mistake was not writing down the aliases in the first place, relying solely on relative paths, and then facing the daunting task of refactoring hundreds of imports. The time spent on initial setup for absolute paths is an investment that prevents much larger future costs.

Actionable Takeaways

• Always Use TypeScript: For new React Native projects, start with TypeScript. It’s the standard for robust development.
• Embrace Absolute Paths: Configure tsconfig.json with baseUrl and paths for cleaner, more maintainable imports. Use a clear alias like @src/*.
• Configure Metro: Ensure metro.config.js is aware of your aliases, either implicitly or explicitly via resolver.alias.
• Structure Your Project: Organize your code logically within the src/ directory and use aliases to reference key areas.
• Test Your Setup: After configuration changes, restart Metro with --reset-cache and test your imports.
• Configure for Testing: Don’t forget to set up moduleNameMapper in your Jest configuration to handle aliases during testing.
• Be Consistent: Maintain consistent casing for file and directory names to avoid case-sensitivity issues.
• Start Simple: Begin with a basic @src/* alias and add more specific aliases only as your project’s complexity demands it.

Setting up your React Native CLI project correctly from the start with TypeScript and absolute paths is a fundamental step towards building high-quality, scalable mobile applications. It might seem like a small detail, but getting it right saves you immense headaches down the road. Happy coding!