feat(VueQueryPlugin): replace useQueryProvider with VueQueryPlugin (#116)

* feat: create VueQueryPlugin

* docs: update Installation section

* feat(plugin): vue2 plugin

* feat(plugin): unmount hook

* build: remove plugin, add external deps

* test: vueQueryPlugin

* docs: update some docs

* fix: import type from core, export plugin options type

* chore: update examples

* feat: multiple clients support

* fix: multi client support

* refactor: query client key helper

* docs: update custom clients page

Co-authored-by: Alexey Antipov <[email protected]>

Author: DamianOsipiuk

README.md

@@ -39,18 +39,15 @@ For topics not covered in vue-query docs visit https://react-query.tanstack.com/
 
 # Quick Start
 
-1. Attach **Vue Query** to the root component of your Vue application
+1. Initialize **Vue Query** via **VueQueryPlugin**
 
    ```ts
-   import { defineComponent } from "vue";
-   import { useQueryProvider } from "vue-query";
+   import { createApp } from "vue";
+   import { VueQueryPlugin } from "vue-query";
 
-   export default defineComponent({
-     name: "App",
-     setup() {
-       useQueryProvider();
-     },
-   });
+   import App from "./App.vue";
+
+   createApp(App).use(VueQueryPlugin).mount("#app");
    ```
 
 2. Use query
@@ -75,9 +72,7 @@ For topics not covered in vue-query docs visit https://react-query.tanstack.com/
 
    ```ts
    const id = ref(1);
-   const queryKey = ["todos", id];
-   const queryFunction = () => getTodos(id);
    const enabled = ref(false);
 
-   const query = useQuery(queryKey, queryFunction, { enabled });
+   const query = useQuery(["todos", id], () => getTodos(id), { enabled });
    ```

docs/getting-started/devtools.md

@@ -6,7 +6,7 @@ When you begin your Vue Query journey, you'll want these DevTools by your side.
 
 The DevTools are bundle split into the vue-query/devtools package. No need to install anything extra, just:
 
-```
+```ts
 import { VueQueryDevTools } from "vue-query/devtools";
 ```
 
@@ -20,7 +20,7 @@ Floating Mode will mount the DevTools as a fixed, floating element in your app a
 
 Place the following code as high in your Vue app as you can. The closer it is to the root of the page, the better it will work!
 
-```
+```vue
 <script lang="ts">
 import { defineComponent } from "vue";
 import { VueQueryDevTools } from "vue-query/devtools";
@@ -56,7 +56,7 @@ export default defineComponent({
 
 Embedded Mode will embed the DevTools as a regular component in your application. You can style it however you'd like after that!
 
-```
+```vue
 <script lang="ts">
 import { defineComponent } from "vue";
 import { VueQueryDevToolsPanel } from "vue-query/devtools";

docs/getting-started/installation.md

@@ -13,3 +13,27 @@ yarn add vue-query
 ```
 
 Vue Query is compatible with Vue 2.x + composition API or 3.x
+
+### Vue Query Initialization
+
+Before starting using Vue Query, you need to initialize it.
+
+There are 2 possible ways to do it.
+
+1. Using `VueQueryPlugin` (recommended)
+
+   ```ts
+   import { VueQueryPlugin } from "vue-query";
+
+   app.use(VueQueryPlugin);
+   ```
+
+2. Calling `useQueryProvider` in the root component
+
+   ```vue
+   <script setup>
+   import { useQueryProvider } from 'vue-query';
+
+   useQueryProvider();
+   </script>
+   ```

docs/guides/custom-clients.md

@@ -4,32 +4,47 @@ Vue Query allows providing custom `QueryClient` for Vue context.
 
 It might be handy when you need to create `QueryClient` beforehand to integrate it with other libraries that do not have access to the Vue context.
 
-For this reason, `useQueryProvider` accepts either QueryClient options or `QueryClient` as a first argument.
+For this reason, `VueQueryPlugin` accepts either `QueryClientConfig` or `QueryClient` as a plugin options.
 
-If You provide QueryClient options, `QueryClient` instance will be created internally and provided to Vue context.
+If You provide `QueryClientConfig`, `QueryClient` instance will be created internally and provided to Vue context.
 
-```js
-useQueryProvider(queryClientOptions);
+```ts
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  queryClientConfig: {
+    defaultOptions: { queries: { staleTime: 3600 } },
+  },
+};
+app.use(VueQueryPlugin, vueQueryPluginOptions);
 ```
 
-```js
-const myClient = new QueryClient(queryClientOptions);
-useQueryProvider(myClient);
+```ts
+const myClient = new QueryClient(queryClientConfig);
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  queryClient: myClient,
+};
+app.use(VueQueryPlugin, vueQueryPluginOptions);
 ```
 
 ### Custom context keys
 
 You can also customize the key under which `QueryClient` will be accessible in Vue context. This can be usefull is you want to avoid name clashing between multiple apps on the same page.
 
-It works both with default, and custom provided `QueryClient`
+It works both with default, and custom `QueryClient`
 
-```js
-useQueryProvider(queryClientOptions, "foo");
+```ts
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  queryClientKey: "Foo",
+};
+app.use(VueQueryPlugin, vueQueryPluginOptions);
 ```
 
-```js
-const myClient = new QueryClient(queryClientOptions);
-useQueryProvider(myClient, "bar");
+```ts
+const myClient = new QueryClient(queryClientConfig);
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  queryClient: myClient,
+  queryClientKey: "Foo",
+};
+app.use(VueQueryPlugin, vueQueryPluginOptions);
 ```
 
 To use the custom client key, You have to provide it as a query options
@@ -48,6 +63,9 @@ Devtools also support this by the `queryClientKeys` prop. You can provide multip
 
 Internally custom key will be combined with default query key as a suffix. But user do not have to worry about it.
 
-```js
-useQueryProvider(queryClientOptions, "foo"); // -> VUE_QUERY_CLIENT:foo
+```ts
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  queryClientKey: "Foo",
+};
+app.use(VueQueryPlugin, vueQueryPluginOptions); // -> VUE_QUERY_CLIENT:Foo
 ```

docs/guides/window-focus-refetching.md

@@ -3,21 +3,22 @@ If a user leaves your application and returns to stale data, **Vue Query automat
 ### Disabling globally
 
 ```ts
-import { defineComponent } from "vue";
-import { useQueryProvider } from "vue-query";
-
-export default defineComponent({
-  name: "App",
-  setup() {
-    useQueryProvider({
-      defaultOptions: {
-        queries: {
-          refetchOnWindowFocus: false,
-        },
+import { createApp } from "vue";
+import { VueQueryPlugin, VueQueryPluginOptions } from "vue-query";
+
+import App from "./App.vue";
+
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  queryClientConfig: {
+    defaultOptions: {
+      queries: {
+        refetchOnWindowFocus: false,
       },
-    });
+    },
   },
-});
+};
+
+createApp(App).use(VueQueryPlugin, vueQueryPluginOptions).mount("#app");
 ```
 
 ### Disabling Per-Query

examples/2.x-basic/src/App.vue

@@ -1,6 +1,5 @@
 <script lang="ts">
 import { defineComponent, ref } from "@vue/composition-api";
-import { useQueryProvider } from "vue-query";
 import { VueQueryDevTools } from "vue-query/devtools";
 
 import Posts from "./Posts.vue";
@@ -10,8 +9,6 @@ export default defineComponent({
   name: "App",
   components: { Posts, Post, VueQueryDevTools },
   setup() {
-    useQueryProvider();
-
     const visitedPosts = ref(new Set());
     const isVisited = (id: number) => visitedPosts.value.has(id);
 

examples/2.x-basic/src/main.ts

@@ -1,9 +1,11 @@
 import Vue from "vue";
 import VueCompositionApi, { createApp, h } from "@vue/composition-api";
+import { VueQueryPlugin } from "vue-query";
 
 import App from "./App.vue";
 
 Vue.use(VueCompositionApi);
+Vue.use(VueQueryPlugin);
 
 createApp({
   render() {

examples/basic/src/App.vue

@@ -1,6 +1,5 @@
 <script lang="ts">
 import { defineComponent, ref } from "vue";
-import { useQueryProvider } from "vue-query";
 import { VueQueryDevTools } from "vue-query/devtools";
 
 import Posts from "./Posts.vue";
@@ -10,8 +9,6 @@ export default defineComponent({
   name: "App",
   components: { Posts, Post, VueQueryDevTools },
   setup() {
-    useQueryProvider();
-
     const visitedPosts = ref(new Set());
     const isVisited = (id: number) => visitedPosts.value.has(id);
 

examples/basic/src/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from "vue";
+import { VueQueryPlugin } from "vue-query";
 
 import App from "./App.vue";
 
-createApp(App).mount("#app");
+createApp(App).use(VueQueryPlugin).mount("#app");

examples/multi-client/src/App.vue

@@ -1,19 +1,12 @@
 <script lang="ts">
 import { defineComponent } from "vue";
-import { useQueryProvider, QueryClient } from "vue-query";
 import { VueQueryDevTools } from "vue-query/devtools";
 
 import Todos from "./Todos.vue";
 
 export default defineComponent({
   name: "App",
   components: { Todos, VueQueryDevTools },
-  setup() {
-    const myClient = new QueryClient();
-    useQueryProvider();
-    useQueryProvider({}, "Foo");
-    useQueryProvider(myClient, "Bar");
-  },
 });
 </script>
 

examples/multi-client/src/main.ts

@@ -1,5 +1,22 @@
 import { createApp } from "vue";
+import { VueQueryPlugin, VueQueryPluginOptions, QueryClient } from "vue-query";
 
 import App from "./App.vue";
 
-createApp(App).mount("#app");
+const fooClient = new QueryClient();
+const barClient = new QueryClient();
+
+const vueQueryPluginOptions: VueQueryPluginOptions = {
+  additionalClients: [
+    {
+      queryClient: fooClient,
+      queryClientKey: "Foo",
+    },
+    {
+      queryClient: barClient,
+      queryClientKey: "Bar",
+    },
+  ],
+};
+
+createApp(App).use(VueQueryPlugin, vueQueryPluginOptions).mount("#app");

examples/multi-page/src/App.vue

@@ -1,16 +1,12 @@
 <script lang="ts">
 import { defineComponent, ref } from "vue";
-
-import { useQueryProvider } from "vue-query";
 import { VueQueryDevTools } from "vue-query/devtools";
 import Page from "./Page.vue";
 
 export default defineComponent({
   name: "App",
   components: { VueQueryDevTools, Page },
   setup() {
-    useQueryProvider();
-
     const firstPage = ref(1);
 
     const changePage = () => {

examples/multi-page/src/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from "vue";
+import { VueQueryPlugin } from "vue-query";
 
 import App from "./App.vue";
 
-createApp(App).mount("#app");
+createApp(App).use(VueQueryPlugin).mount("#app");

examples/simple/src/App.vue

@@ -1,16 +1,12 @@
 <script lang="ts">
 import { defineComponent } from "vue";
-import { useQueryProvider } from "vue-query";
 import { VueQueryDevTools } from "vue-query/devtools";
 
 import Todos from "./Todos.vue";
 
 export default defineComponent({
   name: "App",
   components: { Todos, VueQueryDevTools },
-  setup() {
-    useQueryProvider();
-  },
 });
 </script>
 

examples/simple/src/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from "vue";
+import { VueQueryPlugin } from "vue-query";
 
 import App from "./App.vue";
 
-createApp(App).mount("#app");
+createApp(App).use(VueQueryPlugin).mount("#app");

examples/suspense/src/App.vue

@@ -1,16 +1,12 @@
 <script lang="ts">
 import { defineComponent } from "vue";
-import { useQueryProvider } from "vue-query";
 import { VueQueryDevTools } from "vue-query/devtools";
 
 import Content from "./Content.vue";
 
 export default defineComponent({
   name: "App",
   components: { Content, VueQueryDevTools },
-  setup() {
-    useQueryProvider();
-  },
 });
 </script>
 

examples/suspense/src/main.ts

@@ -1,5 +1,6 @@
 import { createApp } from "vue";
+import { VueQueryPlugin } from "vue-query";
 
 import App from "./App.vue";
 
-createApp(App).mount("#app");
+createApp(App).use(VueQueryPlugin).mount("#app");