Setting up Path Alias in CRA

Jan 27, 2023·4 min read

As your React project expands and components become organized in individual folders, the process of importing them can become cluttered.

Path aliases allow developers to create short, easy-to-remember names for file paths in their project. These aliases can be used in import statements, making it easier to navigate and maintain large code bases.

Without further ado let's see how to configure path aliases in a CRA/Typescript based project.

TypeScript Config

Create tsconfig.paths.json where we will configure baseUrl and paths properties.

tsconfig.paths.json

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@/*": ["*"]
    }
  }
}

Extend tsconfig.json with a newly created tsconfig.paths.json:

tsconfig.json

{
    "compilerOptions": {
        // ...
    },
    "extends": "./tsconfig.paths.json"
}

Observe following project structure:

src
|- components
    |- Button.tsx
    |- Counter.tsx
    |- index.ts # exports everything from src/components
|- config
    |- index.ts
|- feature
    |- auth
        |- components
        |- store
        |- types
        |- utils
        |- index.ts # exports everything from feautre/auth module
    |- chat

With baseUrl set to "src" we can now reference Button.tsx like this: components/Button.

Since we have path alias configured we can also import Button component like this: import {Button} from @/components

export/import components with caution

Button.tsx

// default export
const Button = (...) => {...}
export default Button;

Counter.tsx

// named export
export const Counter = (...) => {...}

index.ts should export components differently based on how they are exported in component file:

index.ts

export { default as Button } from './Button';
export * from './Counter';

Once components are exported in src/components/index.ts it's possible to import them like this:

import { Button, Counter } from '@/components';

Avoid using path aliases for directories if your file is located inside the same directory/module:

feature/auth/components/Login.tsx

// src/feature/auth/components/Login.tsx
// Possible but not recommended
import { UserType } from '@/features/auth';
// Recommended 
import { UserType } from '../types';

feature/auth/index.ts

// this file resolves imports for '@/feature/auth' path
export * from './components/Login'; 
export * from './types';

Importing the UserType from @/features/auth will not work in this scenario.

While we could swap the export order, we should not rely on this method as it can lead to hard to track bugs.

CRACO

We adjusted our TypeScript configuration, and the editor should no longer give us warnings. However, if we try to run the app, we will notice many errors for new imports. The reason for this is that our Webpack configuration needs to be adjusted as well.

In order to fix this we can use craco, a package that helps us override CRA's configurations without the need to eject it.

Install craco:

npm install craco -D

Create craco.config.js file and place it in root:

craco.config.js

const path = require('path');
module.exports = {
  webpack: {
    // set up path alias for project
    alias: {
      '@': path.resolve(__dirname, 'src'),
    },
  },
  jest: {
    configure: {
      // set up path alias for unit tests
      moduleNameMapper: {
        '^@/(.*)$': '<rootDir>/src/$1',
      },
    },
  },
};

jest.config.js

Keep in mind that craco will ignore the jest.config.js and will instead use the settings within the craco.config.js file.

If you want to keep the jest.config.js file you can import it inside craco.config.js:

craco.config.js

const jestConfig = require('./jest.config');
module.exports = {
    webpack: {...},
    jest: {
        configure: jestConfig
    }
}

As the final step we should integrate craco by adding craco scripts inside the package.json file:

package.json

{
    // ...
    scripts: {
        "start": "craco start",
        "build": "craco build",
        "test": "craco test",
    }
}

That's it! We can now safely run the npm start command. The errors should be gone, and we can seamlessly use path aliases in our app.