Using @ alias in React for cleaner React and TypeScript imports from various paths

React along with TypeScript is a wonderful tool for building scalable, maintainable, modern web applications. React + TypeScript is very popular among developers.

In order to import a Button component from same folder we will right it as:

import { Button } from './button';

To import the Button component from a sibling of the parent folder we will write it as:

import { Button } from '../components/button';

And at some point it will go like:

import { Button } from '../../../../components/button';

Why to use @ alias in react?

You see how messy the last statement above has become! @ alias is a workaround to this.

As a React project grows in size and complexity, import statements can become tedious. In particular, the default relative path imports can quickly become long and hinder code readability.

So what is the solution to this? Short answer is, to configure one or more path aliases.

In this article, we will explore how to leverage path aliases to enhance the organization and maintainability of your React and TypeScript projects.

To follow along with this tutorial, you’ll need basic knowledge of JavaScript and TypeScript, along with some familiarity with React. You should also have an existing React and TypeScript project, and make sure Node.js is installed on your machine.

Understanding import statements in React and TypeScript apps

In React and TypeScript apps, developers use import statements to bring in functionality from other modules or files. This practice ensures we develop software that is reusable and modular.

Although import statements are useful in this way, they can lead to problems when they aren’t used properly. The code snippet below shows a typical example of this problem:

import React from 'react';
import { Button } from '../../../../components/button'; // long and messy import :(

function SomeComponent() {
  return <Button />;
};

As you can see, this code snippet uses relative imports from the current file to import the Button component. However, this import pattern is messy because it’s importing the component from a deeply nested directory.

For projects that are relatively small in size, this might not pose much of an issue. But as the project grows, typing and reading long import paths becomes tedious.

In addition, refactoring the project becomes challenging when the directory structure of the imported module changes because it’s tightly coupled to the project file structure.

How path aliases can help simplify import statements

Path aliases let developers define custom shortcuts for import paths, making them cleaner and more intuitive. With path aliases set up, you can have clean and concise imports regardless of the size of the project, as shown in the code snippet below:

import React from 'react';
import { Button } from '@components/button'; // clean and concise import :)

function SomeComponent() {
  return <Button />;
};

By setting up path aliases in a React and TypeScript app, you can simplify import statements, improve code navigation, and enhance the overall development experience.

Configuring path aliases in the `tsconfig.json` OR `tsconfig.app.json` file

You can configure path aliases easily in your project’s tsconfig.json OR tsconfig.app.json file. Normally, the later will take a precedence. This file is usually found at the root of a TypeScript project.

To configure your path aliases in this file, simply add a paths property in the compilerOptions object. Then, you can map path alias names to file paths as shown in the code snippet below:

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

The above code tells the TypeScript compiler to resolve imports from the @/* alias to the ./src/* directory. Once you set up the path alias, you can use it in your import statements.

For example, you can import a Button component in the src/components directory directly from anywhere in the project like this:

import { Button } from "@/components/Button"; 

function App() { 
  return ( <Button>Click Me</Button> )
}

Without a path alias set up, importing the Button component from another file — for example, src/pages/dashboard/profile/settings/index.tsx — would look something like this:

import { Button } from '../../../../components/Button';

function Settings() {
  return (
    <Button>Click Me</Button>
  )
}

You can take this a step further and add more path aliases, which can be beneficial for large projects that store critical parts of the app in well-defined directories. In the tsconfig.json file, update the paths field as shown in the following code snippet:

{
  "compilerOptions": {
    "baseUrl" : "./src",
    "paths": {
      "@components/*": ["./components/*"],
      "@ui/*": ["./components/common/ui/*"],
      "@pages/*": ["./pages/*"],
      "@hooks/*": ["./hooks/*"],
      "@api/*": ["./api/*"],
      "@utils/*": ["./utils/*"],
    }
  }
}

The baseUrl field in the code snippet above is used to make the path aliases shorter to write.

While using Vite, edit the vite.config.ts

import path from 'path';

...

export default defineConfig({
  ...
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

You can add more alias as you did in the examples above.