CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-unocss--nuxt

Nuxt module for UnoCSS that integrates the instant on-demand Atomic CSS engine into Nuxt.js applications

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@unocss/nuxt

@unocss/nuxt is a Nuxt module that integrates UnoCSS, the instant on-demand Atomic CSS engine, into Nuxt.js applications. It provides seamless integration with both Vite and Webpack build systems, enabling developers to use UnoCSS's powerful utility-first CSS framework within Nuxt projects with zero runtime overhead and instant compilation.

Package Information

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

Core Imports

import UnoCSS from "@unocss/nuxt";

For accessing configuration types:

import type { UnocssNuxtOptions } from "@unocss/nuxt";

For TypeScript projects, both the module and types are available:

import UnoCSS, { type UnocssNuxtOptions } from "@unocss/nuxt";

Basic Usage

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [
    '@unocss/nuxt'
  ],
  unocss: {
    // UnoCSS options
    preflight: true,
    icons: true,
  }
});

Architecture

@unocss/nuxt is built around several key components:

  • Nuxt Module: Main integration point that configures UnoCSS within the Nuxt ecosystem
  • Build Integration: Automatic plugin registration for both Vite and Webpack build systems
  • Configuration System: Unified options interface extending UnoCSS core configuration
  • Preset Management: Automatic preset resolution and conflict handling
  • Runtime Components: Vue components like <UnoIcon> for enhanced functionality
  • Development Tools: Nuxt DevTools integration with UnoCSS panel and hot module replacement support

Capabilities

Module Configuration

Core Nuxt module that registers UnoCSS integration with comprehensive configuration options.

/**
 * Default export - Nuxt module for UnoCSS integration
 */
declare const UnoCSS: NuxtModule<UnocssNuxtOptions>;
export default UnoCSS;

/**
 * Configuration options interface
 */
export interface UnocssNuxtOptions extends UserConfig {
  /** CSS Generation mode (Vite only, default: 'global') */
  mode?: 'global' | 'per-module' | 'vue-scoped' | 'dist-chunk' | 'shadow-dom';
  
  /** Automatically inject uno.css entry (default: true) */
  autoImport?: boolean;
  
  /** Inject @unocss/reset/tailwind.css entry (default: false) */
  preflight?: boolean;
  
  /** Disable Nuxt's inline styles for UnoCSS compatibility (default: true) */
  disableNuxtInlineStyle?: boolean;
  
  /** Automatically merge UnoCSS configs from Nuxt layers (default: false) */
  nuxtLayers?: boolean;
  
  /** Path to UnoCSS config file (default: ['uno.config', 'unocss.config']) */
  configFile?: string | string[];
  
  /** @deprecated Position control for uno.css injection - temporarily removed due to incompatibility with Nuxt 3.9 */
  injectPosition?: 'first' | 'last' | number | { after?: string };
  
  /** Install UnoCSS components like <UnoIcon> (default: true) */
  components?: boolean;
  
  /** Enable attributify mode and options (default: false) */
  attributify?: boolean | AttributifyOptions;
  
  /** Enable tagify mode and options (default: false) */
  tagify?: boolean | TagifyOptions;
  
  /** Enable icons preset and options (default: false) */
  icons?: boolean | IconsOptions;
  
  /** Enable web fonts preset and options (default: false) */
  webFonts?: boolean | WebFontsOptions;
  
  /** Enable typography preset and options (default: false) */
  typography?: boolean | TypographyOptions;
  
  /** Enable wind3 preset (default: true) */
  wind3?: boolean | PresetWind3Options;
  
  /** Enable wind4 preset (default: false) */
  wind4?: boolean | PresetWind4Options;
}

Configuration Extensions and Hooks

Extends Nuxt's configuration schema to include UnoCSS options and provides integration hooks.

/**
 * Nuxt configuration schema extensions and hooks
 */
declare module '@nuxt/schema' {
  interface NuxtConfig {
    unocss?: UnocssNuxtOptions;
  }
  
  interface NuxtOptions {
    unocss?: UnocssNuxtOptions;
  }
  
  interface NuxtHooks {
    /**
     * Hook called when UnoCSS config loading is completed
     */
    'unocss:config': (config: UserConfig) => void;
  }
}

Runtime Components

Vue components provided by the module for enhanced UnoCSS integration.

/**
 * UnoIcon Vue component - basic empty div element
 * Available when components option is enabled (default: true)
 * Note: This is a placeholder component with no props or functionality
 */
declare const UnoIcon: DefineComponent;

Types

Core Configuration Interface

interface UnocssNuxtOptions extends UserConfig {
  mode?: 'global' | 'per-module' | 'vue-scoped' | 'dist-chunk' | 'shadow-dom';
  autoImport?: boolean;
  preflight?: boolean;
  disableNuxtInlineStyle?: boolean;
  nuxtLayers?: boolean;
  configFile?: string | string[];
  injectPosition?: 'first' | 'last' | number | { after?: string };
  components?: boolean;
  attributify?: boolean | AttributifyOptions;
  tagify?: boolean | TagifyOptions;
  icons?: boolean | IconsOptions;
  webFonts?: boolean | WebFontsOptions;
  typography?: boolean | TypographyOptions;
  wind3?: boolean | PresetWind3Options;
  wind4?: boolean | PresetWind4Options;
}

Preset Option Types

/**
 * Preset configuration types (imported from respective preset packages)
 */
type AttributifyOptions = import('@unocss/preset-attributify').AttributifyOptions;
type IconsOptions = import('@unocss/preset-icons').IconsOptions;
type TagifyOptions = import('@unocss/preset-tagify').TagifyOptions;
type TypographyOptions = import('@unocss/preset-typography').TypographyOptions;
type WebFontsOptions = import('@unocss/preset-web-fonts').WebFontsOptions;
type PresetWind3Options = import('@unocss/preset-wind3').PresetWind3Options;
type PresetWind4Options = import('@unocss/preset-wind4').PresetWind4Options;

Base Configuration

/**
 * Base UnoCSS configuration (from @unocss/core)
 */
type UserConfig = import('@unocss/core').UserConfig;

Usage Examples

Basic Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@unocss/nuxt'],
  unocss: {
    // Enable preflight (CSS reset)
    preflight: true,
    
    // Enable UnoCSS icons
    icons: true,
    
    // Enable attributify mode
    attributify: true,
    
    // Use global CSS injection mode
    mode: 'global'
  }
});

Advanced Configuration with Custom Presets

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@unocss/nuxt'],
  unocss: {
    preflight: true,
    icons: {
      scale: 1.2,
      warn: true,
      collections: {
        carbon: () => import('@iconify-json/carbon/icons.json').then(i => i.default),
      }
    },
    webFonts: {
      provider: 'google',
      fonts: {
        sans: 'Roboto',
        mono: ['Fira Code', 'Fira Mono:400,700']
      }
    },
    shortcuts: {
      'btn': 'px-4 py-1 rounded inline-block bg-teal-600 text-white cursor-pointer hover:bg-teal-700 disabled:cursor-default disabled:bg-gray-600 disabled:opacity-50',
      'btn-green': 'text-white bg-green-500 hover:bg-green-700',
    },
    rules: [
      [/^m-(\d+)$/, ([, d]) => ({ margin: `${d}px` })],
    ]
  }
});

Using with Nuxt Layers

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@unocss/nuxt'],
  unocss: {
    // Enable automatic config merging from layers
    nuxtLayers: true,
    
    // Specify custom config file paths
    configFile: ['uno.config.ts', 'unocss.config.ts'],
    
    // Base configuration
    preflight: true,
    wind3: true
  }
});

TypeScript Configuration

// nuxt.config.ts
import type { UnocssNuxtOptions } from '@unocss/nuxt';

const unocssConfig: UnocssNuxtOptions = {
  preflight: true,
  icons: true,
  attributify: true,
  wind3: true,
  shortcuts: {
    'custom-btn': 'bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600'
  }
};

export default defineNuxtConfig({
  modules: ['@unocss/nuxt'],
  unocss: unocssConfig
});

Accessing UnoIcon Component

<template>
  <div>
    <!-- UnoIcon component automatically available when components: true -->
    <!-- Note: UnoIcon is currently a placeholder empty div component -->
    <UnoIcon />
  </div>
</template>

Using the Configuration Hook

// plugins/unocss.client.ts
export default defineNuxtPlugin(() => {
  // Hook into UnoCSS configuration
  const nuxtApp = useNuxtApp();
  
  nuxtApp.hook('unocss:config', (config) => {
    console.log('UnoCSS configuration loaded:', config);
  });
});

Development Tools Integration

In development mode, the module automatically registers a UnoCSS panel in Nuxt DevTools, accessible at /__unocss/ for inspecting generated CSS and configuration.

docs

index.md

tile.json