Configuring Vitest for a TypeScript project to support tsconfig path imports can initially seem challenging, especially if you’re not using Vite. However, with the right approach, it’s manageable and rewarding. In this guide, I’ll walk you through the steps needed to configure Vitest in a straightforward TypeScript setup so you can seamlessly use your tsconfig path aliases during testing.
Thank me by sharing on Twitter 🙏
Testing is a crucial part of building reliable software, and having the right configuration ensures your project runs smoothly. I’ll show you how to set up Vitest with the vite-tsconfig-paths plugin, so you can benefit from path aliasing during your tests.
Why Support for tsconfig Paths Matters
When working on larger TypeScript projects, maintaining clear and concise import paths is essential for readability and maintainability. Instead of long, relative paths like import { myFunction } from '../../../utils/myFunction';, you can use path aliases, such as import { myFunction } from '@utils/myFunction';, which makes your code easier to navigate and maintain.
Path aliases are configured in the tsconfig.json file, but getting them to work in your testing environment requires additional setup. This is where Vitest and vite-tsconfig-paths come into play.
Prerequisites
Before we start, ensure that you have an existing TypeScript project set up. Vitest and TypeScript should be installed as part of your project’s development dependencies.
USB Type-C to A Cable 5pack 6ft Braided Fast Charging 3A Quick Charger Cord, 6 Foot Compatible iPhone 17/17 Pro/16e/16/15 Pro Max,Samsung Galaxy S10 S9 S8 Plus, Note 10 9 8, LG V50 V40 G8 G7(Grey)
$7.99 (as of November 26, 2025 01:39 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
Frictionless: 7 Steps to Remove Barriers, Unlock Value, and Outpace Your Competition in the AI Era
$0.99 (as of November 23, 2025 18:34 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)
Bitcoin is for Everyone: Why our financial system is broken and Bitcoin is the solution
$13.90 (as of November 23, 2025 18:34 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)npm install vitest typescript --save-devNow, let’s jump into the steps required to configure Vitest with tsconfig path support.
Step 1: Install vite-tsconfig-paths Plugin
To make Vitest recognize the path aliases defined in tsconfig.json, we’ll use the vite-tsconfig-paths plugin. This plugin automatically reads and maps the paths from tsconfig.json, allowing you to use them in your tests without extra configuration.
Install the vite-tsconfig-paths plugin:
npm install vite-tsconfig-paths --save-devThis plugin will save you the effort of writing manual path resolution logic and seamlessly integrates with Vitest.
Step 2: Create or Update vitest.config.ts
With vite-tsconfig-paths installed, the next step is to configure Vitest. Create or update your vitest.config.ts file to include the plugin.
Here’s a basic example of what vitest.config.ts should look like:
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
test: {
// You can add additional Vitest configuration options here
},
plugins: [tsconfigPaths()],
});By including vite-tsconfig-paths as a plugin, Vitest can now interpret the path aliases defined in your tsconfig.json without any extra steps.
Step 3: Verify Your tsconfig.json Paths
Ensure that your tsconfig.json is set up with the correct path aliases. Below is an example of how your tsconfig.json might look:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@utils/*": ["src/utils/*"],
"@components/*": ["src/components/*"]
}
}
}In this configuration, @utils and @components are aliases that point to the src/utils and src/components directories, respectively.
Make sure that the baseUrl property is set correctly so the compiler can resolve paths from the root of your project.
Step 4: Run Vitest to Confirm Setup
Once your configuration is complete, it’s time to run Vitest and ensure everything is set up properly.
Run the following command to start your tests:
npx vitestIf everything is configured correctly, Vitest should be able to resolve the path aliases without errors, and your tests should run as expected.
Troubleshooting Common Issues
Issue: Path Aliases Not Recognized
If Vitest fails to recognize the path aliases, double-check the following:
- Confirm that
vite-tsconfig-pathsis correctly installed in yournode_modules. - Ensure the paths in
tsconfig.jsonare correctly formatted and match the structure of your project. - Verify that
vitest.config.tsincludes thevite-tsconfig-pathsplugin and that it’s properly imported.
Issue: Setup File Not Working
If you have a test setup file where you import other modules and it doesn’t seem to work as expected, ensure that it’s referenced in the vitest.config.ts:
export default defineConfig({
test: {
setupFiles: ['testSetup.ts'],
},
});Bonus Tip: Using Custom Setup for Node Resolution
While the vite-tsconfig-paths plugin typically handles everything you need, there are cases where you may want to manually handle path aliasing for more complex setups. For that, you can use tsconfig-paths/register.
Create a setup file like testSetup.ts:
import 'tsconfig-paths/register';Reference this file in your Vitest configuration:
export default defineConfig({
test: {
setupFiles: ['testSetup.ts'],
},
});This ensures that TypeScript paths are resolved correctly even if you have custom logic or additional requirements.
Conclusion
Setting up Vitest for TypeScript projects with tsconfig path imports can greatly enhance your development experience, making your code more readable and maintainable. By leveraging the vite-tsconfig-paths plugin, you can seamlessly integrate your existing tsconfig.json paths into your testing environment.
With this setup, your test files can use the same concise path aliases as your main codebase, reducing complexity and making your tests easier to write and understand. Now, your Vitest configuration should be ready to handle your TypeScript path imports effortlessly.
