Add a guide to the documentation for Nuxt 3 Support

[sasial-dev]

As a first time user to the repo, I had a quick look at the issues and there's a lot about Nuxt 3. As a fellow Nuxt 3 user, it would be helpful to have a nuxt/SSR guide.

[Siilwyn]

It's pretty straightforward I think unless I'm missing something?

In Nuxt's plugins directory create a file, e.g. villus.ts with:

import { createClient } from 'villus';

export default defineNuxtPlugin(({ vueApp }) => {
  const client = createClient({
    url: 'https://graphql.datocms.com/',
  });

  vueApp.use(client)
});

Then in your pages you can use useQuery.

[IGassmann]

On top of the plugin configuration (as @Siilwyn demonstrated above), I've also integrated villus with Nuxt's useAsyncData. This enables Villus to work with Nuxt's prerendering and prefetching of linked pages since the data will be embedded into Nuxt's page payload. On top of that, it also enables the use of the transform function.

@logaretm feel free to copy and adjust the code if you want to add to the docs.

Usage Example

const query = graphql(`
  query Comments {
    user {
      post {
        comments {
          id
          name
        }
      }
    }
  }
`);

const { data: comments } = await useAPI({
  query,
  transform: (data) => {
    return data?.user?.post?.comments ?? [];
  },
});

useAPI Code

import type { AsyncDataOptions } from "#app";
import type { KeysOf } from "#app/composables/asyncData";
import {
  getQueryKey,
  type QueryCompositeOptions,
  type QueryVariables,
  useQuery,
} from "villus";

type UseAPIOptions<TData, TVars, TRes> = Omit<
  QueryCompositeOptions<TData, TVars>,
  "fetchOnMount"
> &
  Pick<AsyncDataOptions<TData | null, TRes, KeysOf<TRes>, null>, "transform">;

/**
 * A composable function to fetch data from a GraphQL API.
 * It integrates the Villus GraphQL client with Nuxt’s `useAsyncData`.
 * @param opts
 */
export default function useAPI<
  TData = unknown,
  TVars = QueryVariables,
  TRes = TData,
>(opts: UseAPIOptions<TData, TVars, TRes>) {
  const { execute } = useQuery({
    ...opts,
    fetchOnMount: false,
  });

  const cacheKey = getQueryKey({
    query: toValue(opts.query),
    variables: toValue(opts.variables),
  });

  return useAsyncData(
    String(cacheKey),
    async () => {
      const result = await execute();

      return result.data;
    },
    {
      transform: opts.transform,
    },
  );
}