Vuejs Knowledge Patch

Vue.js Knowledge Patch

Use this patch when changing Vue applications or ecosystem tooling, especially projects using Vue Router, Pinia, Pinia Colada, Nuxt, or Vite integrations. Check the installed package versions before applying version-specific migration advice.

Reference index

Breaking changes and upgrade gates

Move Pinia 4 consumers to ESM

Pinia 4 is ESM-only and requires @vue/devtools-api v8 as a separate dependency. Move CommonJS-only tooling to an ESM-capable path before upgrading:

pnpm add pinia@^4 @vue/devtools-api@^8

Pinia 3 remains usable from CommonJS distribution files despite declaring "type": "module", but its declarations require TypeScript 4.5 or newer. The standalone IIFE builds in both Pinia 3 and Vue Router 5 no longer bundle their Devtools dependency.

Move file-based routing imports into Vue Router

Vue Router 5 incorporates the former unplugin-vue-router functionality. Remove that package, import the Vite plugin from vue-router/vite, and import other adapters, utilities, and types from vue-router/unplugin:

import VueRouter from 'vue-router/vite'
import type { EditableTreeNode, Options } from 'vue-router/unplugin'

Remove the old unplugin-vue-router/client type reference. Prefer generating declarations inside src so normal TypeScript includes find them:

VueRouter({ dts: 'src/routes.d.ts' })

Applications that did not use the old plugin generally need no source changes.

Treat the experimental router entry as ESM-only

Do not load vue-router/experimental from CommonJS. Vite is an optional peer, so projects that do not use the Vite integration need not install it.

Typed query parameters are optional. Invalid query formats warn and are filtered rather than failing route matching, and a query value may be undefined; do not assume a declared query key is present.

Apply Pinia Colada API migrations

Current useQuery() accepts one options object. The old two-argument useQuery and useQueryState forms are removed, and global query defaults belong under queryOptions. Commit current work, then run the appropriate ast-grep rule shipped by the installed package against the source tree:

pnpm --package=@ast-grep/cli dlx ast-grep scan \
  -r node_modules/@pinia/colada/codemods/rules/migration-0-21-to-1-0.yaml \
  -i src

Router data loaders

Install DataLoaderPlugin before the router so it participates in the initial navigation:

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { routes } from 'vue-router/auto-routes'
import { DataLoaderPlugin } from 'vue-router/experimental'

const router = createRouter({ history: createWebHistory(), routes })
const app = createApp({})
app.use(DataLoaderPlugin, { router })
app.use(router)

Loaders run outside component setup, are collected and awaited during navigation, and support parallel deduplicated fetching, loading and error state, SSR, and prefetching. Basic loaders always rerun; the Colada implementation uses @pinia/colada.

Export a loader from its page component. If it is defined elsewhere, re-export it from the page so the router can discover it:

<script lang="ts">
import { defineBasicLoader } from 'vue-router/experimental'

export const useUserData = defineBasicLoader('/users/[id]', (route) =>
  getUserById(route.params.id),
)
</script>

<script setup lang="ts">
const { data, isLoading, error, reload } = useUserData()
</script>

Navigation waits for the loader. Other callers share its fetching instance.

Typed file-based routing

Use the bundled Volar plugins to infer a page's route from its file location, including the types returned by no-argument useRoute() and template $route:

{
  "compilerOptions": { "rootDir": "." },
  "vueCompilerOptions": {
    "plugins": [
      "vue-router/volar/sfc-typed-router",
      "vue-router/volar/sfc-route-blocks"
    ]
  }
}

Validate generated routes and parameter parsers. Missing parsers throw, raw parser types are arrays, and malformed [x+hh] filename escapes are rejected. definePage() also checks params.path and parameter defaults.

Pinia Colada essentials

Register Pinia before Pinia Colada. Plugin factories run in array order:

app.use(createPinia())
app.use(PiniaColada, {
  queryOptions: { staleTime: 5_000, gcTime: 300_000 },
  mutationOptions: {},
  plugins: [],
})

A query needs a serializable array key and a query function. Every reactive input used by the query must also occur in a reactive key. Array order matters, object-property order does not, and undefined object properties are removed. Disable long-lived queries when route inputs are unavailable.

Read the two state axes independently:

refresh() deduplicates and respects freshness. refetch() forces a request. Both resolve to state by default; pass true to rethrow an error. A refetch error preserves prior data, and fetch() must explicitly throw for non-2xx responses to become query errors.

Use defineQueryOptions() for reusable parameterized, type-tagged keys. Use defineQuery() only for once-instantiated shared composables; its extra state is not serialized for SSR. A query held by a long-lived Pinia store is effectively immortal.

Cache and mutation safety

invalidateQueries() marks matches stale and refetches active entries by default. Pass 'all' as its second argument to include inactive matches. Use ensure() before seeding when the cache entry must retain query options and freshness behavior.

mutate() catches failures and returns nothing; mutateAsync() returns a rejecting promise. Awaited hooks keep loading active, and the value returned by onMutate becomes the context for later hooks.

For an optimistic update:

1. Snapshot and replace cached data in onMutate.
2. Call cancelQueries() so stale results are discarded without refetching.
3. Return the old and optimistic values as rollback context.
4. Roll back only if the cache still contains this mutation's optimistic value.
5. Invalidate the affected query on settlement.

Queries intentionally have no local success, error, or settled callbacks. Watch state for component effects or install PiniaColadaQueryHooksPlugin for global fetch hooks. Query meta is fixed when its entry is created and must be serializable for SSR.

Core typing and runtime checks

Use Vue's exported TemplateRef when a template ref needs an explicit type:

import { useTemplateRef, type TemplateRef } from 'vue'

const input: TemplateRef<HTMLInputElement> =
  useTemplateRef<HTMLInputElement>('input')

When upgrading Vue core, regression-test hydration of namespaced elements, pre-hydration text input, current-type changes in <select v-model>, SSR comments, Teleports inside Transitions, nullish slot-prop objects, custom elements with native-property collisions, and defineModel() factory defaults.

Verification checklist

• Exercise kept-alive route reactivation; guards run when the route changes.
• Test overlapping navigations so stale asynchronous scroll results are ignored.
• Validate query loading separately from data status, including retained data after refetch errors.
• Use real createPinia() in Pinia Colada component tests, then flush promises.
• Await asynchronous cache restoration before mounting the application.
• Verify Pinia hydration for skipped non-plain objects and reactive Set or Map state.