Skip to content

docs(upgrade-guide): add Vite overlay stacking and layer order caveats#22848

Draft
johnleider wants to merge 1 commit into
masterfrom
docs/upgrade-guide-vite-layers
Draft

docs(upgrade-guide): add Vite overlay stacking and layer order caveats#22848
johnleider wants to merge 1 commit into
masterfrom
docs/upgrade-guide-vite-layers

Conversation

@johnleider

@johnleider johnleider commented May 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

Two real-world v3→v4 migration issues that aren't currently documented in the upgrade guide, sourced from a production migration.

  • Vite dev-mode overlay z-index — Vite's dep pre-bundler can split Vuetify's overlay modules across two module graphs, creating two useStack instances. The result is overlays rendered inside dialogs stay at z-index 2000 instead of auto-stacking. Documents the symptom, root cause, and fix (optimizeDeps.include + cache clear). Production builds are not affected.

  • Layer order declaration import timing — The @layer order statement must be imported before any Vuetify styles, or the browser establishes layer priority from first-seen order. Documents the correct entrypoint pattern and explains the failure mode.

@oanaCristeaC

oanaCristeaC commented Jul 14, 2026

Copy link
Copy Markdown

Thanks for documenting this, we hit the layer order issue in a production v3 to v4 migration and want to share a caveat: the entrypoint pattern alone (layers file imported first in main.ts) can still fail in production builds with CSS code splitting enabled.

In our app the @layer statement was correctly first in source order and ended up inside the entry CSS, but Rollup emitted a shared Vuetify CSS chunk (ripple-[hash].css, beginning with @layer vuetify-components) and linked it before the entry CSS in the generated index.html, so the browser still parsed Vuetify's layer name first and pinned vuetify-components as the lowest layer, silently inverting our declared order (our reset layer ended up above vuetify-components and stripped component padding app-wide, production builds only, dev looked fine, which matches your "symptoms vary per app depending on build output order" note and seems related to vitejs/vite#21903).

The only placement we found that is immune to chunk link order is an inline <style> with the full @layer order statement in the of index.html, since that is guaranteed to be parsed before every emitted stylesheet link; we keep the layers.scss import as well, but the inline copy is what actually decides. It might be worth mentioning this in the upgrade guide next to the entrypoint pattern, so people with cssCodeSplit (the default) do not diagnose it from scratch.

  <head>
    <meta charset="UTF-8" />
    <style>
      @layer app-base, vuetify-core, vuetify-components, vuetify-overrides,
        vuetify-utilities, vuetify-final, app-components, app-overrides;
    </style>

@J-Sek

J-Sek commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Thanks for letting us know, it is in line with changes to the CLI

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@johnleider @oanaCristeaC @J-Sek