Nx Vite Integration

Nx Vite Integration

Configure Vite as the build tool in Nx workspaces with predictable, cache-friendly defaults.

Mindset

Nx and Vite each have their own opinions about project structure. The integration works by making Vite defer to Nx for path resolution and task orchestration while Nx defers to Vite for bundling. The critical bridge is nxViteTsPaths() — without it, workspace path aliases silently resolve to nothing and builds fail with cryptic module-not-found errors.

Think in two layers: workspace-level (Nx executor targets, cache dirs, project boundaries) and build-level (Vite plugins, rollup options, output formats). Workspace-level decisions live in project.json; build-level decisions live in vite.config.ts. Keep them separate and each layer becomes predictable.

Library mode differs meaningfully from app mode: apps bundle everything together, libraries externalize peer deps to avoid duplication in consumers. The distinction determines whether rollupOptions.external and vite-plugin-dts are needed.

When to Use

Workflow

Step 1: Install Dependencies

Preconditions:

• Nx workspace exists
• Node.js 18+ and package manager available

Commands:

bunx nx add @nx/vite
bun add -d vite

Framework plugin (choose one):

bun add -d @vitejs/plugin-react
# or
bun add -d @vitejs/plugin-vue
# or
bun add -d @sveltejs/vite-plugin-svelte

Expected result:

• @nx/vite and framework plugin installed

Step 2: Generate or Configure Vite

Preconditions:

• Dependencies installed
• Target project exists in Nx

Recommended command:

bunx nx g @nx/vite:configuration <project-name>

Manual baseline (vite.config.ts):

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,
  plugins: [react(), nxViteTsPaths()],
});

Expected result:

• vite.config.ts exists and resolves workspace path aliases

Step 3: Configure Nx Targets

Preconditions:

• Vite config exists

Ensure target config supports:

• build
• serve
• test (Vitest)

Expected result:

• nx run <project>:build and nx run <project>:test are valid targets

Step 4: Add Project-Specific Features

For apps:

• Set outDir and cacheDir relative to workspace root
• Add nxCopyAssetsPlugin if non-public files must be copied
• Add environment replacement plugin when needed

For libraries:

• Configure build.lib
• Externalize peer deps in rollupOptions.external
• Add vite-plugin-dts for declaration output

Expected result:

• Build outputs to dist/ with correct dependency boundaries

Step 5: Verify Setup

Commands:

bunx nx run <project>:build
bunx nx run <project>:test

Expected result:

• Build succeeds
• Tests run with configured environment and cache directories

Anti-Patterns

NEVER: Skip nxViteTsPaths() in Nx Monorepos

Why:

• Workspace path aliases (@org/lib) fail without Nx path plugin integration.

Bad:

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

Good:

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

NEVER: Bundle All Dependencies in Library Mode

Why:

• Bloats bundles and breaks consumer-side tree shaking.

Bad:

build: {
  lib: { entry: 'src/index.ts' },
}

Good:

build: {
  lib: { entry: 'src/index.ts' },
  rollupOptions: {
    external: ['react', 'react-dom', /^@my-org\//],
  },
}

NEVER: Use Project-Relative Cache/Coverage Paths that Ignore Workspace Root

Why:

• Nx caching and output tracking become inconsistent across projects.

Bad:

test: {
  cache: { dir: './node_modules/.vitest' },
  coverage: { reportsDirectory: './coverage' },
}

Good:

test: {
  cache: { dir: '../../node_modules/.vitest/apps/my-app' },
  coverage: { reportsDirectory: '../../coverage/apps/my-app' },
}

NEVER: Mix Unrelated Build and Test Concerns Without Intention

Why:

• Large mixed configs become hard to debug and maintain.

Bad:

• One growing config with ad-hoc overrides and no sectioning.

Good:

• Keep sections intentional (build, server, test, plugins) and validate each step.

Constraint Guidelines

Hard Constraints

• Always include nxViteTsPaths() in Nx monorepos
• Always set root: __dirname
• Always configure outDir and cacheDir relative to workspace root
• Always externalize peer dependencies for published libraries
• Always define test.reporters, test.environment, and deterministic cache/coverage paths

Flexible Choices

• Framework plugin (React, Vue, Svelte, Solid, etc.)
• Output formats (es, cjs, umd) based on consumers
• CSS tooling (PostCSS, Tailwind, vanilla)
• DTS strictness (skipDiagnostics: true/false) based on CI strategy

Verification Commands

bunx nx run <project>:build
bunx nx run <project>:test
bunx @biomejs/biome check skills/nx-vite-integration/
bunx markdownlint-cli2 "skills/nx-vite-integration/**/*.md"

References

• Vite Config Patterns — vite.config.ts options, plugin setup, and resolver configuration for Nx projects
• Nx Vite Plugins — @nx/vite executor options, inferred task configuration, and caching setup
• Library Mode — build.lib configuration, entry point patterns, and DTS generation
• Vitest Integration — Vitest configuration, coverage providers, and Nx test executor setup
• Troubleshooting — common Vite + Nx errors, path resolution failures, and DTS issues