website·Indexed 35 days ago
https://villus.logaretm.com/A minimal and fast GraphQL client for Vue.js with a small API footprint and bundle size under 4kb. It provides composition functions like useQuery(), useMutation(), and useSubscription() to manage GraphQL API states, along with support for TypeScript codegen, query batching, and a plugin-based architecture for caching and file uploads.
<script setup>
import { useClient, cache, fetch } from 'villus';
useClient({
use: [cache(), fetch()],
});
</script>fetch (network execution), cache (in-memory cache), and dedup (removes duplicate pending queries). These are provided via the defaultPlugins() function. To add custom or additional plugins, pass a use array to the useClient configuration.<script setup>
import { useClient, defaultPlugins } from 'villus';
useClient({
url: '/graphql',
use: [...defaultPlugins()], // If not provided, defaultPlugins will be used by default
});
</script>fetch plugin, a batch plugin, or a custom equivalent plugin configured.query passed to useQuery is a ref or computed property, Villus treats it as a reactive query and will automatically re-fetch the data whenever the query string itself changes.<script setup>
import { computed, ref } from 'vue';
import { useQuery } from 'villus';
const id = ref(1);
const FetchTodo = computed(() => {
return `query FetchTodo {
todo (id: ${id.value}) { text }
}
`;
});
const { data } = useQuery({
query: FetchTodo,
});
// Changing id.value will trigger an automatic re-fetch
</script>useSubscription. This function receives the current result and returns a transformed value, which then becomes the data property returned by the hook. This is ideal for extracting specific fields or converting results to booleans.<script setup>
import { useSubscription } from 'villus';
const LastMessage = `
subscription LastMessage {
lastMessage {
id
from
message
}
}
`;
const { data: lastMessage } = useSubscription(
{ query: LastMessage },
({ data }) => {
return data?.lastMessage;
},
);
// lastMessage.value will contain the mapped object
</script>useMutation function allows you to execute GraphQL mutations. Unlike useQuery, it does not execute automatically and does not accept a variables option in its configuration. Mutations always use a network-only cache policy because they represent user actions.<template>
<div>
<div v-if="data">
<p>{{ data.likePost.message }}</p>
</div>
<button @click="execute()">Submit</button>
</div>
</template>
<script setup>
import { useMutation } from 'villus';
const LikePost = `
mutation {
likePost (id: 123) {
message
}
}
`;
const { data, execute } = useMutation(LikePost);
</script>handleSubscriptions plugin to manage them. The plugin requires a subscription forwarder: a function that receives the operation (query and variables) and returns an object containing a subscribe method that accepts an observer.<script setup>
import { useClient, handleSubscriptions, defaultPlugins } from 'villus';
import { createClient } from 'graphql-ws';
// 1. Create your WebSocket client
const wsClient = createClient({
url: 'ws://localhost:9005/graphql',
});
// 2. Define the subscriptions handler
const subscriptionsHandler = handleSubscriptions(operation => {
return {
subscribe: obs => {
wsClient.subscribe(
{
query: operation.query,
variables: operation.variables,
},
obs
);
return {
unsubscribe: () => {
// Handle cleanup if necessary
},
};
},
};
});
// 3. Install the handler in the Villus client
const client = useClient({
url: 'http://localhost:4000/graphql',
use: [subscriptionsHandler, ...defaultPlugins()],
});
</script>useSubscription() reducer function has been flipped to improve TypeScript detection with TypedDocuments and increase versatility. The first argument is now the new subscription result (incoming data), and the second argument is the previous reduced value.// Villus 2.x
function reduceMessages(old, incoming) {
// reduce values
}
// Villus 3.0
function reduceMessages(incoming, old) {
// reduce values
}useSubscription function allows you to listen to GraphQL subscriptions. It accepts a configuration object (containing the query and optional variables) and an optional callback handler to process incoming data and errors.<script setup>
import { ref } from 'vue';
import { useSubscription } from 'villus';
const NewMessages = `
subscription NewMessages {
newMessages {
id
from
message
}
}
`;
const messages = ref([]);
useSubscription({ query: NewMessages }, ({ data, error }) => {
if (data) {
messages.value.push(...data.newMessages);
}
if (error) {
// Handle errors
}
});
</script>useClient within them. This scopes the specific client to the children of that respective parent component.<!-- ComponentA -->
<script setup>
import { useClient } from 'villus';
useClient({
url: '{GITHUB_API_ENDPOINT}',
});
</script>
<!-- ComponentB -->
<script setup>
import { useClient } from 'villus';
useClient({
url: '{MY_API}',
});
</script>