Nuxt Query

Nuxt Query is a module for integrating Tanstack Query (formerly known as Vue Query) into your Nuxt application, providing a powerful solution for fetching, caching, synchronizing and updating server state.

• ✨  Release Notes

Features

• ⚙️   0 config integration
• 💪   Full support of Vue Query config settings
• 🏆   Support for complex QueryClient setup with handlers via hooks
• 🤖   Configurable auto-imports for Vue Query composables
• 🧩   Nuxt DevTools integration for easy debugging

Installation

You can add the module via the Nuxt CLI:

1npx nuxi module add @peterbud/nuxt-query

or via npm:

1pnpm dlx nuxi module add @peterbud/nuxt-query

Configuration

To configure Nuxt Query, update your nuxt.config.ts specifying the options you want for Vue Query:

1// nuxt.config.ts
2export default defineNuxtConfig({
3  modules: ['@peterbud/nuxt-query'],
4  nuxtQuery: {
5    // Specify which Vue Query composable(s) to auto-import
6    autoImports: ['useQuery', 'useMutation'],
7
8    // Enable / disable Nuxt DevTools integration (default: true).
9    devtools: true,
10
11    // These are the same options as the QueryClient 
12    // from @tanstack/vue-query, will be passed 
13    // to the QueryClient constructor
14    // More details: https://tanstack.com/query/v5/docs/reference/QueryClient
15    queryClientOptions: {
16      defaultOptions: {
17        queries: {
18          // for example disable refetching on window focus
19          refetchOnWindowFocus: false,
20
21          // or change the default refetch interval
22          refetchInterval: 5000,
23        },
24      },
25    },
26  },
27})

Then, in your component, you can define and run queries with the useQuery composable (auto-imported):

1// app.vue
2<script setup>
3const getPosts = async () => {
4  await new Promise(resolve => setTimeout(resolve, 2000))
5  return await $fetch('https://jsonplaceholder.typicode.com/posts')
6}
7
8const { isPending, isFetching, isError, data, error } = useQuery({
9  queryKey: ['posts'],
10  queryFn: getPosts,
11})
12</script>

That's it! You can now use Nuxt Query in your Nuxt app ✨

Module Hooks

Nuxt Query provides a hook that you can use in your application if you need a more complex setup for Vue Query, like custom query client with centralized onSuccess or onError handlers, which would not be possible to configure with the options available in the nuxt.config.ts.

The hook is called nuxt-query:configure and you can use it in a plugin to return a custom QueryClient object in the following way:

1// plugins/nuxt-query.ts
2import { QueryClient, QueryCache } from '@tanstack/vue-query'
3
4export default defineNuxtPlugin({
5  enforce: 'pre',
6  setup(nuxtApp) {
7    nuxtApp.hook('nuxt-query:configure', (getPluginOptions) => {
8      const clientOptions = useRuntimeConfig().public.nuxtQuery?.queryClientOptions || {}
9
10      const queryClient = new QueryClient({
11        ...clientOptions,
12        queryCache: new QueryCache({
13          onSuccess: (data: unknown) => console.log('onSuccess', { data }),
14        }),
15      })
16
17      // return the plugin options which will be used
18      // by the module at startup
19      getPluginOptions(queryClient)
20    })
21  },
22})

Nuxt DevTools Integration

Nuxt Query integrates with Nuxt DevTools to provide a dedicated tab for Vue Query, where you can inspect the state of your queries, view their cache, and properties, initiate refetch or remove certain queries and more.

Contribution

1# Install dependencies
2npm install
3
4# Generate type stubs
5npm run dev:prepare
6
7# Develop with the playground
8npm run dev:client
9
10# Build the playground
11npm run dev:build
12
13# Run ESLint
14npm run lint
15
16# Run Vitest
17npm run test
18npm run test:watch
19
20# Build the module
21npm run build
22
23# Release new version
24npm run release

If you want to report a bug, please make sure you have a minimal reproduction of the issue. You can use the minimal example to create a reproduction.