DOCSEARCHbyAlgolia
Submit Docs

Vuetify Nuxt Module

repository·main·Indexed 42 days ago

https://github.com/vuetifyjs/nuxt-module

A zero-config Nuxt module for Vuetify providing auto-imports, tree-shaking, and seamless SSR support. It includes tools for configuring themes, blueprints, date adapters, and icon sets via defineVuetifyConfiguration, as well as runtime hooks like vuetify:before-create and vuetify:ready for advanced customization and dynamic CSP nonce support.

Tokens
25.1K
Snippets
93
Records
124
Agent score
54%

What's inside Vuetify Nuxt Module

  1. Overview of Vuetify Nuxt Module features

    main

    The Vuetify Nuxt Module provides a production-ready UI setup for Nuxt applications with the following core capabilities:

    • Zero-Config: Sensible defaults for most projects.
    • Runtime Extensibility: Customize behavior using Nuxt runtime and module hooks.
    • SSR + Client Hints: Smart SSR detection and HTTP Client Hints support.
    • Flexible Styling: Configuration for Vuetify SASS variables and the styling pipeline.
    • Icon Strategy: Support for pure CSS icons, icon fonts, SVG icons, and multiple icon sets (including UnoCSS presets).
    • i18n + Date Support: Integration with @nuxtjs/i18n and @date-io adapters.
    • Nuxt Layers Support: Ability to share design systems and register custom configurations per layer.
    • DX-first Defaults: Auto-imported composables, optional directives, lab components, and icon pipelines.

  2. Configure Vuetify options when using Blueprints

    main

    When using Blueprints, several standard Vuetify configuration options are ignored because they are managed internally or must be configured via specific module options to avoid conflicts.

    If you need to customize these features, use the following vuetifyOptions keys instead of the standard Vuetify blueprint keys:

    • Components: Use vuetifyOptions.components (the standard components option is ignored).
    • Directives: Use vuetifyOptions.directives (the standard directives option is ignored).
    • Locale: Use vuetifyOptions.locale (the standard locale option is ignored).
    • Date Adapter: Use vuetifyOptions.date (the standard date option is ignored).
    • Icons: Use vuetifyOptions.icons (the standard icons option is ignored).
    • SSR: The ssr flag is managed automatically based on your Nuxt ssr setting and cannot be manually overridden via the blueprint.

    Note on Aliasing: The aliases option only supports defining aliases using strings. Attempting to use a component type in aliases will trigger a build error: Cannot start nuxt: Unexpected token '.'.

  3. Configure date-fns base locale

    main
    When using the date-fns adapter, the locale is resolved at build time from vuetifyOptions.locale.locale. The module maps this value to the corresponding date-fns/locale export. If the locale is unset or unknown, it defaults to enUS and logs a warning. To change the base locale, set vuetifyOptions.locale.locale to a supported Vuetify locale.

  4. How Vuetify 4 handles CSS Cascade Layers

    main

    In Vuetify 4, the module automatically inlines a CSS cascade layer order into the SSR'd <head> to ensure deterministic style priority. This prevents Vuetify's reset styles from accidentally outranking component rules due to non-deterministic injection order.

    The default layer order is: @layer vuetify-core, vuetify-components, vuetify-overrides, vuetify-utilities, vuetify-final;

  5. Automatic tree shaking and auto-import for Vuetify components

    main

    The vuetify-nuxt-module automatically enables tree shaking for Vuetify components. It provides auto-import support using an internal import map (vuetify/dist/json/importMap.json) and the Nuxt components:extend hook. It also handles Vuetify styles via a custom Vite plugin optimized for SSR.

    Important: Do not install any separate Vuetify Vite Plugin in your Nuxt configuration. The module will throw an error if it detects an existing Vuetify Vite Plugin, as the module manages these internally.

  6. How the experimental SASS cache works

    main

    The experimental cache improves performance by pre-compiling Vuetify styles into CSS files.

    1. Hash Calculation: The module generates a hash based on your Vuetify version, Vite version, and the content of your SASS config file.
    2. Cache Check: It looks for a matching hash in node_modules/.cache/vuetify-nuxt-module/styles.
    3. Compilation: If no cache exists, it compiles all Vuetify styles with your SASS variables and stores them in the cache directory.
    4. Serving: During development, it serves these pre-compiled CSS files directly, bypassing the SASS compilation step.

    Benefits:

    • Faster Startup: Initial compilation happens once; subsequent starts are instant.
    • Faster HMR: Changing Vue files does not trigger SASS recompilation for Vuetify styles.
    • Persistence: The cache survives server restarts.

  8. Understand Vuetify Nuxt runtime hooks

    main

    The module uses the vuetify:configuration runtime hook internally to register various Nuxt plugins. While vuetify:configuration is intended for internal use, the module exposes specific plugins based on your configuration:

    • Icons: Always registered. You can provide a custom set by setting vuetifyOptions.icons.defaultSet = 'custom'.
    • i18n: Registered only if the @nuxtjs/i18n module is configured.
    • Date: Registered only if the vuetifyOptions.date configuration option is set.

    For consumer-facing customization, use vuetify:before-create (to modify options before instantiation) or vuetify:ready (to access the instance after instantiation).

  9. Limitations of date formats

    main
    The vuetifyOptions.date.formats configuration only accepts serializable Intl.DateTimeFormatOptions. Because the date configuration is statically serialized, you cannot use function-valued date formats. If your use case requires function-based formatting, you must use a custom date adapter.

  10. Supported icon types in vuetify-nuxt-module

    main

    The module supports three types of icon implementations:

    1. Pure CSS Icons: Recommended approach. This allows you to bundle only the specific SVG icons used in your application within your CSS. This is achieved via the UnoCSS Preset Icons.
    2. Font icons: Traditional icon fonts (e.g., Material Design Icons font).
    3. SVG icons: Individual SVG files.

    Using Pure CSS Icons is the recommended method for optimal performance and bundle size.

  11. Hot-reloading behavior for Vuetify configuration

    main

    Modifying Vuetify configuration files during development triggers a client page reload. The behavior depends on your Nuxt version:

    • Nuxt >= 3.18 (Vite 7) and Nuxt 4: Under SSR, the server-rendered output is refreshed without a full dev-server restart.
    • Nuxt 3.15–3.17 (Vite 6): Under SSR, the module falls back to a full dev-server restart.

    Supported Hot-Reload Options

    Hot-reload covers the following core options:

    • theme
    • defaults
    • components
    • aliases
    • directives
    • locale messages

    Changes requiring a manual dev-server restart

    The following changes cannot be hot-reloaded and require a manual restart:

    • Icon CDN / local CSS <head> links.
    • icon-set / date-adapter changes (their server-rendered modules are not re-evaluated on the fly by the dev SSR runtime).

  12. How includeTransformAssetsUrls normalizes component names

    main

    When you provide component names in the includeTransformAssetsUrls module option, the module automatically applies several normalizations to ensure asset resolution works across different usage patterns. For each entry provided, it adds:

    • Case variations: Kebab-case and PascalCase versions of the name.
    • Attribute variations: Kebab-case, camelCase, and bound (:xxx) attribute versions.

    Note on exclusions: The module will NOT apply these normalizations to original attribute entries that already contain a colon (e.g., xlink:href).