@vueuse/nuxt

VueUse Nuxt Module provides seamless integration of VueUse composables with automatic import capabilities for Nuxt applications. It enables developers to use Vue Composition API utilities from the VueUse library without manual imports, while intelligently avoiding conflicts with Nuxt's built-in utilities.

Package Information

• Package Name: @vueuse/nuxt
• Package Type: npm
• Language: TypeScript
• Installation: npm install @vueuse/nuxt @vueuse/core

Core Imports

// The module is used in nuxt.config.ts, not imported directly in components
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt']
});

For advanced use cases requiring direct access:

import nuxtModule from "@vueuse/nuxt";
import type { VueUseNuxtOptions } from "@vueuse/nuxt";

Basic Usage

Add to your Nuxt configuration to enable auto-imports for VueUse composables:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt'],
  vueuse: {
    // Optional configuration
    autoImports: true,     // Enable auto-imports (default: true)
    ssrHandlers: false     // Enable SSR handlers (default: false, experimental)
  }
});

Once configured, VueUse composables are automatically available in your components:

<template>
  <div>
    <p>Mouse position: {{ x }}, {{ y }}</p>
    <p>Window size: {{ width }} x {{ height }}</p>
  </div>
</template>

<script setup>
// No imports needed - auto-imported by the module
const { x, y } = useMouse();
const { width, height } = useWindowSize();
</script>

Architecture

The module consists of several key components:

• Module Definition: Nuxt module that configures VueUse integration
• Auto-Import System: Automatically imports VueUse composables from multiple packages
• Conflict Avoidance: Disables VueUse functions that conflict with Nuxt built-ins
• SSR Support: Optional server-side rendering handlers for VueUse composables
• Build Integration: Configures Vite and build settings for optimal VueUse usage

Capabilities

Nuxt Module Configuration

The main export that configures VueUse integration in Nuxt applications.

/**
 * VueUse Nuxt Module - Auto import for VueUse in Nuxt
 */
declare const _default: NuxtModule<VueUseNuxtOptions>;
export default _default;

interface VueUseNuxtOptions {
  /**
   * Enable/disable auto imports for VueUse composables
   * @default true
   */
  autoImports?: boolean;
  
  /**
   * Enable/disable SSR handlers for server-side rendering
   * @experimental
   * @default false
   */
  ssrHandlers?: boolean;
}

// Supporting types from @nuxt/kit
interface NuxtModule<T = any> {
  (options?: T, nuxt?: any): void | Promise<void>;
  meta?: ModuleMeta;
}

Module Metadata

Module identification and configuration key.

interface ModuleMeta {
  name: 'vueuse';
  configKey: 'vueuse';
}

Disabled Functions

VueUse functions that are disabled to avoid conflicts with Nuxt built-ins.

/**
 * Functions disabled from auto-import to avoid conflicts with Nuxt
 */
declare const disabledFunctions: readonly [
  'toRefs',
  'toRef', 
  'toValue',
  'useFetch',
  'useCookie',
  'useHead',
  'useStorage',
  'useImage'
];

Supported VueUse Packages

VueUse packages that are automatically imported when available.

/**
 * VueUse packages supported for auto-import
 */
declare const packages: readonly [
  'core',
  'shared',
  'components', 
  'motion',
  'firebase',
  'rxjs',
  'sound',
  'math',
  'router'
];

Auto-Import Configuration

The module automatically imports VueUse composables from the following packages when they are available:

• @vueuse/core - Core composables (always available)
• @vueuse/components - Vue component utilities
• @vueuse/motion - Animation and motion utilities
• @vueuse/firebase - Firebase integration
• @vueuse/rxjs - RxJS integration
• @vueuse/sound - Audio utilities
• @vueuse/math - Mathematical utilities
• @vueuse/router - Vue Router utilities

Only functions with names 4+ characters that don't conflict with disabled functions are auto-imported.

SSR Plugin Support

When ssrHandlers: true is enabled, the module provides server-side rendering support:

/**
 * SSR handlers for VueUse composables in server context
 */
interface SSRHandlers {
  /**
   * Provides cookie-based storage implementation for SSR
   * Uses Nuxt's useCookie for persistent storage
   */
  getDefaultStorage(): {
    getItem(key: string): any;
    setItem(key: string, value: any): void;
    removeItem(key: string): void;
  };
  
  /**
   * Updates HTML attributes in SSR context
   * Supports 'html' and 'body' selectors via useHead
   */
  updateHTMLAttrs(selector: 'html' | 'body', attr: string, value: any): void;
}

Build Configuration

The module automatically configures:

• Vite Optimization: Excludes VueUse packages from dependency optimization
• Transpilation: Adds VueUse packages to Nuxt's transpile targets
• DevTools Integration: Adds VueUse documentation tab to Nuxt DevTools

Nuxt Schema Extensions

Extends Nuxt's configuration types to include VueUse options.

declare module '@nuxt/schema' {
  interface NuxtConfig {
    vueuse?: VueUseNuxtOptions;
  }
  
  interface NuxtOptions {
    vueuse?: VueUseNuxtOptions;
  }
}

Error Handling

The module handles several error scenarios:

• Missing Packages: Gracefully skips auto-imports for VueUse packages that aren't installed
• SSR Conflicts: When SSR handlers encounter unsupported meta selectors, throws descriptive errors
• Build Issues: Automatically configures build settings to prevent common VueUse + Nuxt conflicts

CommonJS Compatibility

A CommonJS proxy is provided for legacy module systems:

/**
 * CommonJS proxy to bypass jiti transforms from Nuxt 2
 */
declare const commonjsProxy: {
  default: (...args: any[]) => Promise<any>;
  meta: {
    name: string;
    version: string;
    [key: string]: any;
  };
};