or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vite-tsconfig-paths

Vite plugin that enables path resolution using TypeScript's path mapping configuration from tsconfig.json files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vite-tsconfig-paths@5.1.x

To install, run

npx @tessl/cli install tessl/npm-vite-tsconfig-paths@5.1.1

index.mddocs/

vite-tsconfig-paths

Vite plugin enabling TypeScript path mapping from tsconfig.json. Resolves path aliases and baseUrl, eliminating relative path imports.

Installation: npm install --save-dev vite-tsconfig-paths

Core API

Import

import tsconfigPaths from 'vite-tsconfig-paths';
import type { PluginOptions } from 'vite-tsconfig-paths';

Plugin Factory

/**
 * Creates Vite plugin for TypeScript path resolution
 * @param opts - Configuration options
 * @returns Vite Plugin (name: 'vite-tsconfig-paths', enforce: 'pre')
 */
function default(opts?: PluginOptions): Plugin;

Configuration Interface

interface PluginOptions {
  /**
   * Directory to crawl for tsconfig.json files
   * Default: viteConfig.root (with projects) or searchForWorkspaceRoot(viteConfig.root)
   */
  root?: string;

  /**
   * Explicit tsconfig.json paths (disables auto-crawl)
   * Absolute or relative to root
   */
  projects?: string[];

  /**
   * Enable path resolution for non-TS/JS files (.vue, .svelte, .mdx)
   * Use when allowJs insufficient
   */
  loose?: boolean;

  /**
   * Use TypeScript compiler for parsing (adds ~600ms startup)
   * Only for non-standard tsconfig
   */
  parseNative?: boolean;

  /**
   * Suppress tsconfig.json error warnings
   * Useful in monorepos
   */
  ignoreConfigErrors?: boolean;

  /**
   * Config file names to search
   * Default: ["tsconfig.json", "jsconfig.json"]
   */
  configNames?: string[];

  /**
   * Directory skip predicate (.git, node_modules always skipped)
   * Returns true to skip
   */
  skip?: (dir: string) => boolean;
}

TypeScript Config Schema

interface TSConfig {
  include?: string[];
  exclude?: string[];
  compilerOptions?: {
    baseUrl?: string;
    paths?: { [path: string]: string[] };
    allowJs?: boolean;
    checkJs?: boolean;
    outDir?: string;
  };
}

Usage Patterns

Basic Setup

import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});

Monorepo (Auto-Discovery)

export default defineConfig({
  plugins: [
    tsconfigPaths({
      root: '../../', // Workspace root
    }),
  ],
});

Monorepo (Explicit Projects)

export default defineConfig({
  plugins: [
    tsconfigPaths({
      root: '.',
      projects: [
        './packages/app/tsconfig.json',
        './packages/shared/tsconfig.json',
      ],
    }),
  ],
});

Vue/Svelte (Loose Mode)

import vue from '@vitejs/plugin-vue';
// or: import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [
    vue(), // or svelte()
    tsconfigPaths({ loose: true }),
  ],
});

Custom Directory Skipping

export default defineConfig({
  plugins: [
    tsconfigPaths({
      skip: (dir) => ['test', 'dist', 'build'].includes(dir),
    }),
  ],
});

Ignore Config Errors

export default defineConfig({
  plugins: [
    tsconfigPaths({ ignoreConfigErrors: true }),
  ],
});

TSConfig Path Mapping

Standard Aliases

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
      "@utils/*": ["utils/*"],
      "@/*": ["*"]
    }
  }
}
// Usage
import Button from '@components/Button';
import { formatDate } from '@utils/date';
import { config } from '@/config';

BaseUrl Only

{
  "compilerOptions": {
    "baseUrl": "./src"
  }
}
// import { config } from 'config';
// Resolves: ./src/config → node_modules/config (fallback)

Include/Exclude Patterns

{
  "include": ["src/**/*"],
  "exclude": ["src/**/*.test.ts"]
}

Path resolution only applies to matching files.

AllowJs for Non-TS Files

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

Enables resolution for .vue, .svelte, .mdx, .js, .jsx, .mjs. Use loose: true option if insufficient.

Project References

{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/utils" }
  ]
}

Plugin auto-loads and processes referenced projects.

Architecture

The plugin operates through Vite's plugin system with these components:

  • TSConfig Discovery: Automatically locates and parses tsconfig.json files in project hierarchy, supporting monorepo structures with multiple configuration files
  • Path Mapping Resolution: Converts TypeScript path mappings into resolved module paths that Vite can understand
  • Resolver Integration: Hooks into Vite's module resolution system at 'pre' enforcement stage to intercept and resolve imports
  • Include/Exclude Support: Respects TypeScript's include/exclude patterns to determine which files use path resolution
  • Caching Layer: Maintains resolution caches for performance optimization during development

Debug Mode

Enable debug logging using the DEBUG environment variable:

DEBUG=vite-tsconfig-paths vite              # General logging
DEBUG=vite-tsconfig-paths:resolve vite      # Resolution details
DEBUG=vite-tsconfig-paths* vite             # All debug output

Debug output includes:

  • TSConfig file discovery and loading
  • Path mapping compilation
  • Module resolution attempts
  • Include/exclude pattern matching
  • Configuration options

Common Use Cases

Standard TypeScript Project

// vite.config.ts
import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
});
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": { "@/*": ["*"] }
  }
}

Monorepo with Multiple Packages

// apps/web/vite.config.ts
import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    tsconfigPaths({
      root: '../../', // Auto-discover all tsconfig files in workspace
    }),
  ],
});

Vue 3 Project with Path Aliases

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    vue(),
    tsconfigPaths({ loose: true }), // Enable path resolution in .vue files
  ],
});
// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["src/components/*"],
      "@/composables/*": ["src/composables/*"],
      "@/stores/*": ["src/stores/*"]
    },
    "allowJs": true
  }
}

Svelte Project

// vite.config.ts
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    svelte(),
    tsconfigPaths({ loose: true }), // Enable path resolution in .svelte files
  ],
});

Troubleshooting

Paths Not Resolving

  1. Verify tsconfig.json has baseUrl or paths defined
  2. Check file is included in tsconfig's include patterns
  3. Ensure file extension is supported (see allowJs section)
  4. Enable debug logging: DEBUG=vite-tsconfig-paths:resolve vite
  5. Try loose: true option for non-TypeScript files

Monorepo Issues

  1. Use root option to specify workspace root
  2. Try projects option to explicitly list tsconfig files
  3. Use skip option to exclude large directories (improves performance)
  4. Enable ignoreConfigErrors if some tsconfig files have issues

Performance Issues

  1. Use skip option to exclude unnecessary directories
  2. Avoid parseNative: true unless absolutely necessary (~600ms startup cost)
  3. Consider explicit projects list instead of auto-discovery in very large monorepos

Vite Dev Server Not Updating

Path mapping changes in tsconfig.json require restarting the Vite dev server. The plugin does not hot-reload configuration changes.

Limitations

  • CSS files: Due to a Vite limitation, CSS files and CSS dialects cannot be resolved with this plugin
  • Configuration hot-reload: Changes to path mappings in tsconfig.json require restarting the Vite dev server
  • Virtual modules: Modules with \0 in their ID (Vite virtual modules) are not processed