Nx Vite Plugin Reference

Core Nx-specific plugins for Vite projects.

nxViteTsPaths

Import:

import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

Purpose:

• Resolves workspace TypeScript path aliases in monorepos.

Use:

plugins: [react(), nxViteTsPaths()]

When required:

• Any Nx workspace with cross-project imports (@scope/lib).

nxCopyAssetsPlugin

Import:

import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';

Purpose:

• Copies non-public assets into output during build.

Use:

plugins: [nxCopyAssetsPlugin(['*.md', 'LICENSE'])]

Notes:

• public/ files are already handled by Vite without this plugin.
• Use for files outside standard public asset flow.

replaceFiles (Rollup Replace Files Plugin)

Import:

import { replaceFiles } from '@nx/vite/plugins/rollup-replace-files.plugin';

Purpose:

• Replaces files for environment-specific builds.

Use:

plugins: [
  replaceFiles([
    {
      replace: 'apps/web/src/environments/environment.ts',
      with: 'apps/web/src/environments/environment.prod.ts',
    },
  ]),
]

Plugin Ordering Guidance

Suggested order:

1. Framework plugin (react, vue, svelte)
2. nxViteTsPaths()
3. Asset/environment plugins
4. DTS plugin (for libraries)

Reason:

• Framework and path resolution should stabilize module graph before output-time plugins.

Troubleshooting

Common Nx + Vite issues and direct fixes.

TypeScript Paths Not Resolving

Symptoms:

• Imports like @my-org/lib fail during dev/build.

Fix:

• Add nxViteTsPaths() to plugins.
• Confirm project tsconfig path aliases are correct.

Build Output in Wrong Directory

Symptoms:

• Artifacts appear inside project folder or unexpected dist path.

Fix:

• Set root: __dirname.
• Set build.outDir relative to workspace root (not project root).

Library Types Missing for Consumers

Symptoms:

• Published package compiles but downstream TS projects fail type lookup.

Fix:

• Add vite-plugin-dts and verify output.
• Ensure package metadata points to types (types/exports).

Assets Not Copied

Symptoms:

• Markdown/license/static files missing from output.

Fix:

• Use nxCopyAssetsPlugin([...]) for non-public files.
• Keep public/ assets in Vite public flow.

Tests Not Running or Cached Correctly

Symptoms:

• Vitest behaves inconsistently between local and CI.

Fix:

• Set test.reporters, test.environment, and deterministic cache/coverage dirs.
• Validate with nx run <project>:test.

Slow Library Builds

Symptoms:

• Build times grow significantly after adding DTS generation.

Fix:

• Set skipDiagnostics: true in local development.
• Keep strict diagnostics in CI or release checks.

Migration Regressions from Webpack

Symptoms:

• Feature parity gaps after moving to Vite.

Fix:

• Identify Webpack-only behavior first.
• Replace loader/plugin behavior with Vite equivalents incrementally.
• Stop migration for unsupported critical features.

Vite Config Patterns (Nx)

Use these patterns when creating vite.config.ts for Nx apps and libraries.

App Baseline (React)

/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/apps/my-app',
  plugins: [react(), nxViteTsPaths()],
  build: {
    outDir: '../../dist/apps/my-app',
    reportCompressedSize: true,
    commonjsOptions: { transformMixedEsModules: true },
  },
  server: { port: 4200, host: 'localhost' },
  preview: { port: 4300, host: 'localhost' },
});

App Baseline (Vue)

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

export default defineConfig({
  root: __dirname,
  plugins: [vue(), nxViteTsPaths()],
  cacheDir: '../../node_modules/.vite/apps/my-app',
  build: { outDir: '../../dist/apps/my-app' },
});

App Baseline (Svelte)

import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

export default defineConfig({
  root: __dirname,
  plugins: [svelte(), nxViteTsPaths()],
  cacheDir: '../../node_modules/.vite/apps/my-app',
  build: { outDir: '../../dist/apps/my-app' },
});

Proxy Pattern

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:3000',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, ''),
    },
  },
}

Environment Replacement Pattern

import { replaceFiles } from '@nx/vite/plugins/rollup-replace-files.plugin';

plugins: [
  replaceFiles([
    {
      replace: 'apps/my-app/src/environments/environment.ts',
      with: 'apps/my-app/src/environments/environment.prod.ts',
    },
  ]),
]

Path Depth Rule

Always compute paths from project root to workspace root:

• apps/my-app and libs/my-lib usually use ../../
• packages/pkg may use ../

Example mapping:

Vitest Integration (Nx)

Use deterministic Vitest config that works with Nx caching and coverage outputs.

Baseline Test Config

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    reporters: ['default'],
    globals: true,
    environment: 'jsdom',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    cache: {
      dir: '../../node_modules/.vitest/apps/my-app',
    },
    coverage: {
      provider: 'v8',
      reportsDirectory: '../../coverage/apps/my-app',
    },
  },
});

Environment Selection

• jsdom: UI components, browser APIs
• node: backend logic, utility libraries
• happy-dom: alternative DOM runtime

Required Nx-Friendly Settings

• reporters: keep explicit (['default'])
• cache.dir: workspace-relative path
• coverage.reportsDirectory: workspace-relative path

Separate Config Option

If test concerns become large, use a dedicated vitest.config.ts and keep vite.config.ts focused on build/serve.

Validation Commands

bunx nx run <project>:test
bunx nx run <project>:test --coverage