Why We’re Still Talking About Project Structure

Alright, let’s be honest. In 2026, we’re still having the same heart-to-hearts about project structure in React Native as we did five years ago. Why? Because as projects grow, the simple ../.. in your import statements starts to feel less like a charming quirk and more like a gnawing irritation. It’s not just about aesthetics; a well-organized project is a joy to work on, easier to debug, and significantly less prone to those mind-bending import errors that suck hours out of your day. This is especially true when you’re dealing with the robustness that TypeScript brings to the table. Today, we’re diving deep into setting up a **React Native CLI setup** that embraces TypeScript and leverages absolute paths for a cleaner, more maintainable codebase. We’ll cover the setup, the common gotchas, and what’s truly worked in real-world scenarios.

The Genesis: A Fresh React Native CLI Project (2026 Edition)

Forget Expo for a moment. When you need that granular control, the React Native CLI is your battleground. Let’s start with the foundation. The command to get a new project going is straightforward:

npx react-native init MyAwesomeApp

This gives you the bare-bones React Native structure. It’s functional, but it’s not opinionated about how you organize your components, services, or utilities. We’ll change that.

Sprinkling in TypeScript: The ‘Why’ and ‘How’

If you’re not already using TypeScript in your React Native projects, you’re leaving a lot of potential on the table. The benefits are massive:

• Early Error Detection: Catching type-related bugs during development, not in production.
• Improved Readability and Maintainability: Explicit types act as documentation.
• Better Tooling: Enhanced autocompletion, refactoring, and code navigation in your IDE.
• Robustness for Large Teams: Enforces contracts between different parts of the application.

Adding TypeScript to an existing React Native CLI project is also pretty painless:

cd MyAwesomeApp
npx @react-native-community/cli-init --template typescript

This command installs the necessary TypeScript dependencies and sets up a basic tsconfig.json file. You’ll immediately notice the .tsx extensions and the new tsconfig.json in your project root. Now, our project is ready to embrace type safety.

The Absolute Path Revelation: Bidding Farewell to Relative Hell

This is where the real magic happens for project structure. Imagine this:

// Before absolute paths
import MyComponent from '../../../../components/common/MyComponent';
import apiService from '../../../../services/apiService';

Every time you move a file, you have to meticulously re-check and update all the relative imports that point to it. It’s a recipe for disaster. Absolute paths, on the other hand, treat your project’s source directory as the root.

So, instead, you’d have:

// With absolute paths
import MyComponent from 'components/common/MyComponent';
import apiService from 'services/apiService';

This makes imports:

• Shorter and Cleaner: Easier to read.
• More Resilient to File Movement: Moving a file within its own directory doesn’t break imports.
• More Semantic: Imports clearly state the ‘module’ they’re coming from (e.g., ‘components’, ‘utils’).

Configuring TypeScript (`tsconfig.json`) for Absolute Paths

The first step to enabling absolute paths is configuring tsconfig.json. We need to tell TypeScript where our source code lives so it can resolve these module paths correctly.

Open your tsconfig.json file. You’ll want to modify or add the following properties:

1. `baseUrl`

This tells the TypeScript compiler where to look for non-relative module references. Usually, this will be your src directory.

2. `paths`

This is the core of our absolute path setup. It’s a mapping from module names (or patterns) to locations relative to baseUrl.

Here’s a common configuration:

{
"compilerOptions": {
"target": "esnext",
"module": "commonjs",
"lib": ["es2017", "esnext.asynciterators"],
"allowJs": true,
"jsx": "react-native",
"noEmit": true,
"strict": false,
"experimentalDecorators": true,
"moduleResolution": "node",
"baseUrl": ".",
"paths": {
"@/*": ["src/*"],
"@components/*": ["src/components/*"],
"@utils/*": ["src/utils/*"],
"@services/*": ["src/services/*"],
"@hooks/*": ["src/hooks/*"],
"@assets/*": ["src/assets/*"]
},
"allowSyntheticDefaultImports": true,
"esModuleInterop": true,
"skipLibCheck": true, // This is important for React Native dependencies
"resolveJsonModule": true
},
"exclude": [
"node_modules",
"babel.config.js",
"metro.config.js",
"jest/setup.js",
"*.test.js",
"*.spec.js"
]
}

Explanation:

• "baseUrl": ".": This tells TypeScript to resolve modules relative to the project root. We’ll later tell Metro to also use this.
• "paths": { ... }: This is where we define our aliases. For example, "@/*": ["src/*"] means any import starting with @/ will be looked for inside the src directory. You can define as many specific aliases as you need (e.g., @components/*, @utils/*). This is a pattern I’ve found incredibly useful.
• "skipLibCheck": true: Essential for React Native projects, as many native modules might have declaration files that cause type checking issues.

After this change, you should be able to start using these aliases in your TypeScript files. For example:

import MyButton from '@components/common/MyButton';
import { apiClient } from '@services/apiClient';

Your IDE should now resolve these paths correctly, and TypeScript will understand them. However, there’s a crucial second step.

Taming the Metro Bundler: Aliases for Everything!

This is where many developers get stuck. TypeScript knows about your absolute paths, but the Metro bundler (React Native’s JavaScript bundler) doesn’t. If you try to import using your new aliases without configuring Metro, you’ll get errors like Unable to resolve module '...'. We need to tell Metro about these aliases too.

This is done via the metro.config.js file in your project root.

The metro.config.js Dance

The Metro configuration file is where you can customize how Metro bundles your code. We’ll use the resolver.alias option to mirror our TypeScript paths.

Here’s how you’d update your metro.config.js:

const { getDefaultConfig } = require('metro-config');
module.exports = (async () => {
const {
resolver: {
sourceExts,
assetExts,
},
} = await getDefaultConfig();
return {
transformer: {
babelTransformerPath: require.resolve('react-native-svg-transformer'),
getTransformOptions: async () => ({
transform: {
experimentalImportSupport: false,
inlineRequires: true,
},
}),
},
resolver: {
// Add SVGs to assetExts
assetExts: assetExts.filter((ext) => ext !== 'svg'),
// Add the SVG transformer to sourceExts
sourceExts: [...sourceExts.filter((ext) => ext !== 'svg'), 'svg'],
// --- Our Absolute Path Aliases ---
alias: {
'@': require('path').resolve(__dirname, 'src'),
'@components': require('path').resolve(__dirname, 'src/components'),
'@utils': require('path').resolve(__dirname, 'src/utils'),
'@services': require('path').resolve(__dirname, 'src/services'),
'@hooks': require('path').resolve(__dirname, 'src/hooks'),
'@assets': require('path').resolve(__dirname, 'src/assets')
}
},
};
})();

Explanation:

• We’re getting the default Metro configuration first.
• The key part is the resolver.alias object. It maps your alias (e.g., '@') to the actual file system path. require('path').resolve(__dirname, 'src') resolves to the absolute path of your src directory.
• I’ve also included common patterns for handling SVGs with react-native-svg-transformer, which is a frequent requirement in React Native projects.

Important Note: Sometimes, you might need to clear the Metro bundler cache after making changes to metro.config.js. You can do this with:

npx react-native start --reset-cache

Or, more commonly, by deleting the cache folder manually (usually in /tmp/metro-* on Linux/macOS) and then restarting the packager.

Putting it All Together: A Practical Example

Let’s say you have the following project structure:

MyAwesomeApp/
├── src/
│ ├── components/
│ │ └── Button.tsx
│ ├── services/
│ │ └── api.ts
│ └── App.tsx
├── index.js
├── App.tsx (the entry point defined in index.js)
├── tsconfig.json
└── metro.config.js

In your App.tsx (or any other file), you can now import like this:

// src/App.tsx
import React from 'react';
import { View, Text } from 'react-native';
import Button from '@components/Button'; // Absolute path import!
import { fetchData } from '@services/api'; // Absolute path import!
const App = () => {
const [data, setData] = React.useState(null);
React.useEffect(() => {
const getData = async () => {
const result = await fetchData();
setData(result);
};
getData();
}, []);
return (

Welcome to My Awesome App!
 console.log('Button clicked!')} />
{data && Data: {JSON.stringify(data)}}

);
};
export default App;

And your src/services/api.ts might look like:

// src/services/api.ts
export const fetchData = async () => {
// Replace with your actual API call
return new Promise(resolve => setTimeout(() => resolve({ message: "Hello from API!" }), 1000));
};

This setup provides a clean, organized, and maintainable way to manage your project’s modules.

Common Pitfalls and How We Dodged Them

Even with the best intentions, you can run into trouble. Here are some common issues:

• Forgetting to Configure Metro: This is the most frequent mistake. TypeScript sees the paths, but Metro doesn’t. Always remember to update metro.config.js.
• Incorrect Path in `metro.config.js`: Double-check that require('path').resolve(__dirname, 'your/src/folder') points to the correct directory where your aliased modules reside. A typo here will cause silent failures or errors.
• Cache Issues: Metro is notorious for its caching. If changes don’t seem to be picked up, the first step should be --reset-cache.
• Conflicting Aliases: If you have overlapping aliases (e.g., @/* and @src/* both pointing to src), Metro might get confused. Keep your aliases distinct and logical.
• Not Using a `src` Directory: While not strictly required for absolute paths, using a src directory is a de facto standard and makes configuring baseUrl and your aliases much cleaner. If you don’t use src, your baseUrl and paths would likely be '.' and ['./components/*'] etc., which is a bit less organized.
• IDE Syncing: Sometimes, your IDE (VS Code, WebStorm) might not pick up the `metro.config.js` changes immediately for linting or intellisense. Restarting the IDE or forcing a re-index can help.

What Didn’t Quite Work (or Took Too Long)

Early on, I experimented with trying to make tsconfig.json the single source of truth for paths and hoping Metro would magically pick it up. Spoiler: it doesn’t. The explicit configuration in metro.config.js is non-negotiable. I also spent a bit too much time trying to achieve this without a dedicated `src` folder, which only made the `paths` configuration in `tsconfig.json` more verbose and harder to manage. Embracing the `src` directory alongside absolute paths is a winning combination.

Another approach that seemed promising but often led to complexity was trying to dynamically generate paths from `tsconfig.json` into `metro.config.js`. While possible, it added a layer of indirection that was harder to debug when things went wrong. Keeping them manually aligned, though slightly redundant, proved more robust.

Beyond the Basics: Scaling with Monorepos and Advanced Configs

For larger applications or teams building multiple related packages, you might eventually look into monorepos using tools like Nx or Yarn Workspaces / pnpm Workspaces. In a monorepo setup, your metro.config.js becomes more sophisticated. You’ll need to configure Metro to properly resolve modules across different packages within your monorepo. This often involves:

• Using react-native-monorepo-helper or similar tools to inject workspace package locations into Metro’s resolver.
• Potentially customizing watchFolders and resolver.nodeModulesPaths in metro.config.js to include your other packages.

While this is beyond the scope of a basic setup, understanding how to configure Metro for absolute paths is a fundamental step towards managing complex monorepo structures.

Actionable Takeaways for Your Next React Native Project

To recap, here’s your checklist for a robust React Native CLI setup with TypeScript and absolute paths:

1. Initialize your project with TypeScript: Use npx react-native init YourAppName --template typescript (or update an existing one).
2. Configure tsconfig.json: Set up baseUrl (typically .) and define your paths aliases (e.g., '@/*': ['src/*'], '@components/*': ['src/components/*']). Ensure you have a src directory for better organization.
3. Configure metro.config.js: Crucially, add your aliases to the resolver.alias property, mapping them to their absolute file system paths (e.g., '@': require('path').resolve(__dirname, 'src')).
4. Reset Cache When Necessary: If things don’t work, run your start command with --reset-cache.
5. Organize with a `src` Directory: It simplifies configuration and improves project clarity.
6. Test Thoroughly: After setup, run your app on both iOS and Android simulators/devices to catch any bundler or import issues.

By investing a little time in this setup early on, you’ll save yourself a mountain of debugging headaches down the line. Happy coding!