How to Use Path Aliases with Vite, TypeScript and VSCode

Why Use Path Aliases?

When working on a project, you may find yourself importing files from deep within your project directory. This can lead to long and hard-to-read import paths. Path aliases allow you to define a shorter alias for these paths, making your imports cleaner and more readable.

import SomeComponents from "../uicomponents/anotherFolder/SomeComponents";
import OtherComponents from "../../components/OtherComponents";

Here’s an example where import statements start to look a little messy.

We’re having to worry about where components are relative to the current component we’re working in. Is it a folder up? Two folders up? Somewhere else?

In small projects you probably won’t notice this too much as your components will likely be close together or in just one folder. But as your project grows and you start to add more and more components, this can become a real headache.

There has to be a better way!

import SomeComponents from "@/uicomponents/anotherFolder/SomeComponents";
import OtherComponents from "@/components/OtherComponents";

In the above snippet we’re pointing to the same files but we’re doing in in a non-relative way. We’re saying no matter where we are in the project, we can always find our components with @components or @uicomponents which point to src/components and src/uicomponents respectively. This looks much cleaner and is easier to read.

There is some set up required to make this work:

TypeScript need to know about these aliases so it knows where to look for the files.
We also need to let Vite know so it can bundle the project correctly
VSCode needs to be told how to use these aliases so it can provide intellisense for our imports.

Configuring TypeScript

To get started we need to update our tsconfig.json file, specifically the compiler options. We need to add a baseURL which we’ll point at our src directory and then we need to add a paths object which will contain our aliases.

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

With this config TypeScript will now look in the src directory for all imports that start with @/. This means we can now import files like this:

import MyComponent from "@/components/MyComponent";

But you can add as many aliases as you like. Just add them to the paths object like so:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@assets/*": ["src/assets/*"],
      "@lib/*": ["src/lib/*"],
      "@types": ["src/lib/types.ts"],
      "@contexts/*": ["src/components/contexts/*"],
      "@stores/*": ["src/components/stores/*"]
    }
  }
}

Now TypeScript will know that @components points to src/components and @assets points to src/assets and so on.

Configuring Vite

TypeScript is now happy with our aliases but Vite doesn’t know about them yet so our imports won’t work when we run the project. To fix this we need to update our vite.config.ts file.

import path from "path";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: [
      {
        find: "@",
        replacement: path.resolve(__dirname, "src"),
      },
      {
        find: "@components",
        replacement: path.resolve(__dirname, "src/components"),
      },
      {
        find: "@assets",
        replacement: path.resolve(__dirname, "src/assets"),
      },
      {
        find: "@lib",
        replacement: path.resolve(__dirname, "src/lib"),
      },
      {
        find: "@types",
        replacement: path.resolve(__dirname, "src/lib/types.ts"),
      },
      {
        find: "@contexts",
        replacement: path.resolve(__dirname, "src/components/contexts"),
      },
      {
        find: "@stores",
        replacement: path.resolve(__dirname, "src/components/stores"),
      },
    ],
  },
});

Note: You may get an error when trying to import path and using __dirname in your Vite config file. To fix this you can install the @types/node package. Go to your terminal and run:
npm install --save-dev @types/node.

Here we’re making use of Node’s path module to resolve our aliases to their correct paths. For our purposes, you can think of Vite performing a find and replace on our imports. So when we import @components/MyComponent Vite will replace @components with the path to the src/components directory.

It might seem like a shame that Vite can’t just take the aliases defined in the tsconfig.json file but this comes down to Vite and TypeScript having a separation of concerns. TypeScript is responsible for type checking and Vite is responsible for bundling. This separation allows for more flexibility and control over the project.

There is a plugin called vite-tsconfig-paths which can do a lot of this for you. It will read the aliases from your tsconfig.json file and apply them to your Vite project. You can find more information on this plugin here.

I prefer a more manual approach as it makes aliases more intentional and means your project is less reliant on plugins.

Configuring VSCode

You could stop here and your project would work fine but if you try to make use of VSCode’s intellisense for your imports, you may notice that VSCode keeps trying to use relative paths. This gets old very quickly.

The good news is you don’t need to make or edit yet another config file, you can solve this by changing a setting in VSCode. Open up VSCode’s settings using the cog in the bottom left corner and choose Settings.

Search for a setting called typescript.preferences.importModuleSpecifier and set it to non-relative. This will tell VSCode to use the path aliases we’ve set up in our tsconfig.json file.

VSCode TypeScript Preferences Import Module Specifier

Note: You may need to restart VSCode for this setting to take effect.

Wrapping Up

And that’s it! If you haven’t tried using path aliases before, give it a shot. Chances are you will never look back. Not having to think about exactly where your components, hooks and other files are located in your project affords you extra brain space to focus on building out your project.