villus

library3.5.2jsnpmunverified

A small and fast GraphQL client for Vue.js, version 3.5.2. It provides a minimal composable-based API for querying GraphQL APIs, with built-in caching, deduplication, and batch support. Unlike Apollo Client, villus is lightweight and focused, offering plugins for subscriptions and file uploads. It ships TypeScript types and supports Vue 2.7+ and 3.x, with Suspense support. Compatible with GraphQL 0.11-16. Released actively, with frequent updates.

api-client

npm install villus

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VILLUS

villus

api-clientjavascriptv3.5.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useClient

✓ import { useClient } from 'villus'

✗ const { useClient } = require('villus')

ESM-only, CJS not supported. 'useClient' sets up the global client.

useQuery

✓ import { useQuery } from 'villus'

✗ import { useQuery } from 'villus/useQuery'

All exports are top-level from 'villus'.

useMutation

✓ import { useMutation } from 'villus'

✗ import useMutation from 'villus'

Named import, not default.

VillusClient

✓ import { VillusClient } from 'villus'

✗ import VillusClient from 'villus'

VillusClient is a class exported as named export. For advanced usage.

Sets up a villus client and executes a simple GraphQL query in a Vue 3 component using the Composition API.

import { createApp } from 'vue'; import { useClient, useQuery } from 'villus'; const app = createApp({ setup() { useClient({ url: process.env.VITE_GRAPHQL_URL ?? 'http://localhost:4000/graphql', }); return {}; }, render() { return null; }, }); // In a child component: const AllPosts = ` query AllPosts { posts { title } } `; const { data, isFetching, error } = useQuery({ query: AllPosts, }); console.log(data.value);

Debug

Known issues

breakingvillus v2 to v3 migration: useClient() no longer returns a client; it directly configures the global client.

fix

Remove variable assignment from useClient(). For multiple clients, use 'villus/multi-client' subpackage.

affects: >=3.0.0

breakinguseQuery and useMutation now return a reactive 'data' ref instead of a plain object.

fix

Access data via data.value in script, or use v-if in template to wait for data.

affects: >=3.0.0

deprecatedThe 'cachePolicy' option in useClient is deprecated; use 'cachePolicy' in plugin options instead.

fix

Pass cachePolicy to the 'cache' plugin: import { cache } from 'villus' and use plugins: [cache({ policy: 'cache-and-network' })].

affects: >=3.2.0

gotchaVillus requires 'fetch' polyfill in older browsers or Node.js. Not included.

fix

Install unfetch (client) or node-fetch (server) and assign to globalThis.fetch.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'query')

useQuery called before useClient is set up, or useClient not called in an ancestor component.

fix

Ensure useClient() is called in a parent component (e.g., App.vue) before any child uses useQuery.

Cannot find module 'villus' or its corresponding type declarations.

TypeScript unable to resolve villus; missing package or wrong import path.

fix

Install villus: npm install villus graphql. Ensure tsconfig has 'moduleResolution': 'node' and 'esModuleInterop': true.

data is not a function

Using useQuery result as if data is a function (e.g., data()), but it's a ref.

fix

Access data as a ref: data.value in <script setup> or use v-if in template.

Upgrade

Version history

3.5.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/logaretm/villus ↗

packagevillus ↗

homepagehttps://github.com/logaretm/villus#readme ↗