villus Documentation

villus is a minimal GraphQL client designed for Vue.js. It provides a lightweight alternative to Apollo Client, focusing on flexibility and a small footprint while providing essential quality-of-life features like query caching out of the box. It is suitable for both small projects and large, complex applications.

Key features include:

• Minimal & Tiny: Small footprint with only what you need to query GraphQL APIs.
• Caching: Simple and convenient query caching enabled by default.
• TypeScript Support: Written in TypeScript for better developer experience.
• Vue Integration: Provides minimal Vue.js components and full Composition API support.

The multipart plugin has the following compatibility constraints:

• Batching: The multipart plugin is not supported by the @villus/batch plugin.
• Supported Fetchers: It can only be used with the fetch plugin or your own custom fetchers.

You can make a query reactive by passing a Ref or ComputedRef as the query argument. useQuery will automatically watch these for changes and re-fetch the query whenever the value updates.

Note: Objects created with reactive() are not supported as reactive queries; you must use Ref or ComputedRef (e.g., via computed()).

The fetch plugin is a critical component of the Villus pipeline. While Villus uses a pipeline of plugins to process GraphQL operations, the fetch plugin is responsible for the actual execution of queries and mutations against your GraphQL API.

Note: The fetch plugin is included by default in any Villus client unless you explicitly override the plugin configuration.

Villus supports reactive queries by watching the query property itself. If you pass a computed property or a ref as the query argument, Villus will automatically re-fetch the query whenever the underlying query string/AST changes.

<script setup>
import { computed, ref } from 'vue';
import { useQuery } from 'villus';

const id = ref(1);

// The query is reactive; changing id.value triggers a re-fetch
const FetchTodo = computed(() => {
  return `query FetchTodo { todo (id: ${id.value}) { text } }`;
});

const { data } = useQuery({
  query: FetchTodo,
});
</script>

You can associate queries with an array of string tags. These tags allow you to manage cache invalidation and refetching, typically in coordination with mutations:

• Cache Clearing: A mutation configured with clearCacheTags containing a specific tag will clear the cache for all queries marked with that same tag.
• Automatic Refetching: Mutations can be configured to automatically refetch all queries that share a specific tag after the mutation completes.

To tag a query, pass the tags array in the useQuery options object.

const { data } = useQuery({
  query: GetPosts,
  tags: ['all_posts'],
});

To test components that use useQuery or useMutation, you need to mock the GraphQL API responses. There are two primary approaches:

1. Mocking the fetch function: A simpler approach where you intercept the global fetch and return a manual response.
2. Using MSW (Mock Service Worker): The recommended approach. MSW allows you to mock an API server at the network level, which enables testing GraphQL error responses and provides a testing environment that closely mimics real-world behavior.

Villus supports multiple providers. You can query different GraphQL APIs within the same application by creating separate parent components for each client. Each parent component uses useClient with a different URL, effectively scoping that client to its own subtree of components.

<script setup>
// ComponentA
useClient({
  url: '{GITHUB_API_ENDPOINT}',
});
</script>

<script setup>
// ComponentB
useClient({
  url: '{MY_API}',
});
</script>

If you want data to represent a specific part of the response rather than the whole object, pass a mapping function as the second argument. This function receives the new result as the first argument.

Note: When mapping, the returned value becomes the new data. The function can return any type (e.g., a specific field or a boolean).

<script setup>
import { useSubscription } from 'villus';

const LastMessage = `
  subscription LastMessage {
    lastMessage {
      id
      from
      message
    }
  }
`;

const { data: lastMessage } = useSubscription(
  {
    query: LastMessage,
  },
  ({ data }) => {
    // remember that data can be null
    return data?.lastMessage;
  },
);
</script>

The Cache Plugin is an in-memory cache that stores query results. It clears automatically when the page reloads or the client is destroyed. Note that the plugin only applies caching logic to queries; mutations always require a fresh response from the server.

The plugin supports four cache policies:

• cache-first: Returns cached data if available; otherwise, fetches from the network.
• network-only: Always fetches from the network and does not store the result in the cache.
• cache-and-network: Returns cached data immediately (if available), then fetches fresh data from the network to update the reactive state and the cache.
• cache-only: Returns cached data if available; otherwise, returns an empty response without errors.