Appearance

Vue Query Plugin ​

File Information ​

  • Path: app/plugins/vue-query.ts
  • Purpose: Global TanStack Vue Query (v5) configuration: QueryClient, caching, global error handling, and SSR hydration
  • Load order: Must run after Pinia and API client (see Plugins index)

Overview ​

The Vue Query plugin creates and configures the application-wide QueryClient. It sets default options for queries and mutations, subscribes to the query and mutation caches to handle errors globally (401 → logout, others → snackbar via getApiErrorMessage), and manages SSR dehydrate/hydrate so server-fetched data is available on the client without duplicate requests.

Configuration ​

  • staleTime: From runtimeConfig.public.queryStaleTime (environment: NUXT_PUBLIC_QUERY_STALE_TIME). Default: 5 minutes. Used as the default for all queries.
  • gcTime: 10 minutes (garbage collection time for inactive cache entries).
  • retry: Queries 3, mutations 1.
  • refetchOnWindowFocus: false (queries); refetchOnReconnect: true; refetchOnMount: true.

Global Error Handling ​

  • Query errors: If the query is not disabled/paused, 401 triggers authStore.logout(); other errors show useSnackbar().showError(getApiErrorMessage(error)).
  • Mutation errors: Same logic (401 → logout, others → snackbar).
  • Errors are processed only on the client; the plugin uses ~/utils/error for consistent message extraction.

SSR ​

  • Server: On app:rendered, the plugin dehydrates the QueryClient state into useState('vue-query').
  • Client: On load, the plugin hydrates the QueryClient from that state so cached server data is used.

Provide ​

  • queryClient: The QueryClient instance is provided to the Nuxt app so composables and useQueryClient() from @tanstack/vue-query use the same client.