4.3.0

New "client context"

Docs - PR

You can now pass typed context from your Nuxt app to the GraphQL middleware using a new feature called client options. This is a file you can create (similar to server options) called graphqlMiddleware.clientOptions.ts. It currently supports a single method called buildClientContext(). It allows you to define a type and build a context object. When using a composable such as useGraphqlQuery() this context will be built before performing the request and encoded as a query param. On the server side you then have access to this context inside all server options methods:

graphqlMiddleware.clientOptions.ts

import { defineGraphqlClientOptions } from 'nuxt-graphql-middleware/dist/runtime/clientOptions'

export default defineGraphqlClientOptions<{
  country: 'US' | 'DE' | 'FR'
}>({
  buildClientContext() {
    const country = useCurrentCountry()
    return {
      country: country.value,
    }
  },
})

graphqlMiddleware.serverOptions.ts

import { defineGraphqlServerOptions } from 'nuxt-graphql-middleware/dist/runtime/serverOptions'

export default defineGraphqlServerOptions({
  serverFetchOptions: function (event, _operation, operationName, context) {
    // Pass the current country as a header when making a request to the
    // GraphQL server.
    return {
      headers: {
        'x-current-country': context.client?.country || 'US',
      },
    }
  },
})

Server utils

Both useGraphqlQuery and useGraphqlMutation were previously available via import from a special alias inside a nitro context (such as event handlers):

import { useGraphqlQuery } from '#graphql-composable'

export default defineEventHandler(async () => {
  const data = await useGraphqlQuery('users')
  return data.data.users.map((v) => v.email)
})

Unfortunately this has lead to some issues with a recent Nuxt update; most notably the method's arguments and return value were completely untyped. Because of that these two methods are now available as server utils and are automatically imported. You will have to remove all existing imports:

export default defineEventHandler(async () => {
  const data = await useGraphqlQuery('users')
  return data.data.users.map((v) => v.email)
})

These server utils also support the new "client context" feature, but the context you define in graphqlMiddleware.clientOptions.ts is not used here. You can however pass the object directly when using the utils:

const data = await useGraphqlQuery({
  name: 'testClientOptions',
  clientContext: {
    country: 'US',
  },
})

What's Changed

• Don't log patterns to the console by @lewebsimple in #42
• fix(docs): correct typo in file upload setting name by @asonnleitner in #44

New Contributors

• @lewebsimple made their first contribution in #42

Full Changelog: release/4.2.0...release/4.3.0

4.2.0

What's Changed

Nuxt 4 Compatibility

The module is now compatible with the new folder structure when compatibilityVersion: 4 is enabled.

• The location for the server options file now defaults to <serverDir>/graphqlMiddleware.serverOptions. When using default configuration this would be ./server/graphqlMiddleware.serverOptions. The existing location inside the app folder continues to work, but is deprecated and support for it will be removed in the next major release
• Alias resolving has been refactored: Options like schemaPath or autoImportPatterns now resolve the same as everywhere in Nuxt. For example a schemaPath value of ~~/schema.graphql will resolve to the rootDir set by Nuxt (<rootDir>/schema.graphql in this example).
• Same applies for manual fragment imports: #import '~/components/User/fragment.graphql' will try to import the file from <srcDir>/components/User/fragment.graphql (in classic Nuxt 3 folder structure this would be ./components, when using Nuxt 4 ./app/components)

Support for Layers

With the changes mentioned above support for layers was also improved. Fragment imports from layers should now work, e.g. #import '~~/layers/my-layer/graphql/fragment.graphql.

Various

• Empty GraphQL files will be skipped during codegen to prevent an obvious error from being logged

Full Changelog: release/4.1.1...release/4.2.0

4.1.1

What's Changed

• feat(logging): enhance GraphQL document validation logging by @asonnleitner in #35
• fix: actually use default autoImportPatterns (#36)

Full Changelog: release/4.1.0...release/4.1.1

4.1.0

New Features

New composable: useAsyncGraphqlQuery()

A wrapper around useAsyncData and useGraphqlQuery to perform a single GraphQL query. Docs

const { data } = await useAsyncGraphqlQuery('users')

Automatic Fragment Inlining

When enabled using the autoInlineFragments: true option, fragments are automatically inlined in query, mutation or other fragment files, without having to write import comments. Docs

# No more import needed!
query userById($id: ID!) {
  ...getUserQuery
}

Support for mutations with file uploads

A new useGraphqlUploadMutation composable is available when setting the module option enableFileUploads to true. This also adds a new server handler to handle multipart formdata file uploads. Docs

async function upload(image: File) {
  const data = await useGraphqlUploadMutation('uploadImage', {
    image,
  })
}

Client Caching

A new client side (browser) caching of GraphQL queries can be enabled. The caching is opt-in, meaning nothing is cached by default. Docs

const { data } = await useAsyncGraphqlQuery('users', null, {
  graphqlCaching: {
    client: true,
  },
})

Improved GraphQL Response Typings

When implementing a onServerResponse or doGraphqlRequest method in the server options, it's now possible to add types for any additional properties you might want to add to the response:

import { defineGraphqlServerOptions } from 'nuxt-graphql-middleware/dist/runtime/serverOptions'
import { getCacheTags } from '~/helpers'

type Cacheability = {
  cacheTags: string[]
  maxAge: number
}

export default defineGraphqlServerOptions<{ __cacheability?: Cacheability }>({
  onServerResponse(event, graphqlResponse) {
    const cacheTags = getCacheTags(graphqlResponse)
    return {
      data: graphqlResponse._data.data,
      errors: graphqlResponse._data.errors,
      __cacheability: {
        cacheTags,
        maxAge: 7200,
      },
    }
  },
}

These additional properties are then used across all response types (composables or useFetch/$fetch).

Improved Types

Types have been improved everywhere. For example, when setting a custom onResponse method via useGraphqlState, the response type is now an union type of all possible queries and mutations:

export default defineNuxtPlugin({
  name: 'playground-state-plugin',
  dependsOn: ['nuxt-graphql-middleware-provide-state'],
  setup() {
    const state = useGraphqlState()
    if (!state) {
      return
    }
    state.fetchOptions = {
      onResponse(ctx) {
        const data = ctx.response?._data?.data
        if (data && 'users' in data) {
          console.log(data.users[0].id)
        }
      },
    }
  },
})

This type is also available to import if needed:

import type { GraphqlMiddlewareResponseUnion } from '#build/nuxt-graphql-middleware'

There is also a new type called GraphqlResponseTyped that can be imported from #graphql-middleware-server-options-build. It contains a fully typed response, where data is the union type and that includes any custom properties defined via defineGraphqlServerOptions

What's Changed

• fix serverOptions types exports (#22) by @Applelo in #23
• fix: adopt forward-compatible approach to builder:watch by @danielroe in #27
• fix: opt in to import.meta.* properties by @danielroe in #26
• docs: use new nuxi module add command in installation by @danielroe in #28
• chore: indicate compatibility with new v4 major by @danielroe in #31
• add custom fragment import helpers and remove @graphql-fragment… by @asonnleitner in #33

New Contributors

• @Applelo made their first contribution in #23
• @asonnleitner made their first contribution in #33

Full Changelog: release/4.0.0...release/4.1.0

Fix versioning, latest Nuxt compatibility

This release fixes the versioning issue on npm and adds compatibility with latest Nuxt 3 versions.

Version 2.0

Merge pull request #2 from dulnan/feature/vite-support

Rework using siroc and vite compatibility