nuxt-graphql-middleware 5.2.2 → 5.3.0

package/docs/configuration/client-options.md

@@ -0,0 +1,121 @@
+# Client Options
+
+`nuxt-graphql-middleware` will look for a file called
+`graphqlMiddleware.clientOptions.ts` in your app dir. This file can export so
+called "client options" which are used when _making a request to the GraphQL
+middleware_.
+
+::: warning
+
+Note that the client options are only used in a **Nuxt app context** - they are
+not used when using `useGraphqlQuery` or other utils in a **Nitro context** such
+as event handlers.
+
+:::
+
+## Defining Client Options
+
+When using a composable such as `useGraphqlQuery`, behind the scenes it will use
+`$fetch` to make a request to the GraphQL middleware server route. Sometimes
+it's useful to pass some additional context with this request that can then be
+used on the server.
+
+Similar to [serverOptions](/configuration/server-options), you can create a file
+called `graphqlMiddleware.clientOptions.ts` in your `app` directory (usually
+`<rootDir>/app`).
+
+::: code-group
+
+```typescript [~/app/graphqlMiddleware.clientOptions.ts]
+import { defineGraphqlClientOptions } from 'nuxt-graphql-middleware/client-options'
+
+export default defineGraphqlClientOptions({})
+```
+
+:::
+
+## Defining Client Context
+
+Implement the `buildClientContext()` method to return an object with string
+values.
+
+::: code-group
+
+```typescript [~/app/graphqlMiddleware.clientOptions.ts]
+import { defineGraphqlClientOptions } from 'nuxt-graphql-middleware/client-options'
+
+export default defineGraphqlClientOptions<{
+  language: string
+  country: string
+}>({
+  buildClientContext() {
+    const language = useCurrentLanguage()
+    const country = useCurrentCountry()
+    return {
+      language: language.value,
+      country: country.value,
+    }
+  },
+})
+```
+
+:::
+
+::: info
+
+By passing a generic in `defineGraphqlClientOptions` you can define the type of
+your context object.
+
+:::
+
+Now everytime a request to the middleware is made with a composable such as
+`useGraphqlQuery`, the composable will call the `buildClientContext` method to
+get the current context. It then maps each property of the returned object to a
+query parameter while prefixing the property to prevent collisions with
+potential query parameters from GraphQL variables.
+
+So for example, when making a GraphQL query like so:
+
+```typescript
+const data = await useGraphqlQuery('loadProduct', {
+  id: '123',
+})
+```
+
+The composable will make a fetch request to this URL.
+
+`/api/graphql_middleware/loadProduct?id=123&__gqlc_language=en&__gqlc_country=US`
+
+Both the `language` and `country` properties we returned in the object in
+`buildClientContext()` are appended as prefixed query parameters.
+
+## Using Client Context
+
+On the server you can then access this client context from within all
+[serverOptions](/configuration/server-options) methods:
+
+::: code-group
+
+```typescript [~/server/graphqlMiddleware.serverOptions.ts]
+import { defineGraphqlServerOptions } from 'nuxt-graphql-middleware/server-options'
+
+export default defineGraphqlServerOptions({
+  graphqlEndpoint(event, operation, operationName, context) {
+    // Use the language from the client context.
+    const language = context?.client?.language || 'en'
+    return `http://backend_server/${language}/graphql`
+  },
+
+  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',
+      },
+    }
+  },
+})
+```
+
+:::

package/docs/configuration/module-hooks.md

@@ -0,0 +1,112 @@
+# Module Hooks
+
+You can hook into the module's build to add or alter the documents.
+
+## `nuxt-graphql-middleware:init`
+
+This hook is called right before processing the initial set of GraphQL
+documents, after all modules have been initialised. It allows you to add
+additional documents as strings.
+
+### Example in `nuxt.config.ts`
+
+```typescript
+export default defineNuxtConfig({
+  hooks: {
+    'nuxt-graphql-middleware:init': (ctx) => {
+      ctx.addDocument(
+        'queryFromHook',
+        `query queryFromHook {
+           users {
+             id
+           }
+         }`,
+      )
+    },
+  },
+})
+```
+
+### Example in Custom Module
+
+```typescript
+import { defineNuxtModule, createResolver } from '@nuxt/kit'
+import { fileURLToPath } from 'url'
+import { isObjectType } from 'graphql'
+
+const QUERY = `
+query loadComments {
+  comments {
+    ...comment
+  }
+}
+`
+
+export default defineNuxtModule({
+  meta: {
+    name: 'nuxt-graphql-middleware-playground',
+  },
+  setup(_options, nuxt) {
+    // Resolve files relative to this module.
+    const resolver = createResolver(import.meta.url)
+
+    nuxt.hooks.hookOnce('nuxt-graphql-middleware:init', (context) => {
+      // Make sure the schema contains a required type.
+      if (!context.schemaHasType('Comment')) {
+        throw new Error('Module requires type "Comment" to exist.')
+      }
+
+      context.addDocument('queryFromModule', QUERY)
+
+      // Add a document on disk via its absolute path.
+      const filePath = resolver.resolve('./graphql/queryFromDisk.graphql')
+      context.addImportFile(filePath)
+
+      // Get a GraphQLNamedType from the schema.
+      const type = context.schemaGetType('Comment')!
+      if (!isObjectType(type)) {
+        throw new Error('"Comment" should be an object type.')
+      }
+
+      // Check for existance of certain fields on a type.
+      const fields = type.getFields()
+      const hasAuthorField = !!fields.author
+
+      // Add a fragment with conditional fields.
+      context.addDocument(
+        'commentFragmentFromModule',
+        `fragment comment on Comment {
+           ${hasAuthorField ? 'author' : ''}
+           body
+           subject
+         }`,
+      )
+    })
+  },
+})
+```
+
+## `nuxt-graphql-middleware:build`
+
+This hook is called whenever the internal state of all GraphQL documents was
+rebuilt. It receives a context object that contains a `output` property
+containing the Generator output from
+[graphql-typescript-deluxe](https://github.com/dulnan/graphql-typescript-deluxe).
+It allows you to access all operations or fragments.
+
+### Example in `nuxt.config.ts`
+
+```typescript
+export default defineNuxtConfig({
+  hooks: {
+    'nuxt-graphql-middleware:build': (ctx) => {
+      const fragments = ctx.output.getFragments()
+      console.log('Collected Fragments')
+      fragments.forEach((v) => {
+        // v.node contains the FragmentDefinitionNode from 'graphql'.
+        console.log(v.node.name.value)
+      })
+    },
+  },
+})
+```

package/docs/configuration/module-utils.md

@@ -0,0 +1,53 @@
+# Module Utils
+
+These utils can be imported from `nuxt-graphql-middleware/utils`.
+
+::: warning
+
+These utils can **only** be used in other modules. Importing them in any other
+place will not work.
+
+:::
+
+## `useGraphqlModuleContext()`
+
+This util exposes the `ModuleContext` instance of `nuxt-graphql-middleware`.
+It's the same instance also available from [hooks](/configuration/module-hooks).
+
+### Example
+
+In this example the module conditionally enables features based on the existance
+of certain types and fields in the schema.
+
+```typescript
+import { defineNuxtModule } from '@nuxt/kit'
+import { useGraphqlModuleContext } from 'nuxt-graphql-middleware/utils'
+import { isObjectType } from 'graphql'
+
+type Feature = 'comments' | 'blog' | 'analytics'
+
+export default defineNuxtModule({
+  meta: {
+    name: 'my-custom-module',
+  },
+  setup(_options, nuxt) {
+    const enabledFeatures: Feature[] = []
+
+    const context = useGraphqlModuleContext()
+
+    // Feature is available if this type exists.
+    if (context.schemaHasType('Comment')) {
+      enabledFeatures.push('comments')
+    }
+
+    // Feature is available if a mutation called "trackPageView" exists.
+    const Mutation = context.schemaGetType('Mutation')
+    if (isObjectType(Mutation)) {
+      const fields = Mutation.getFields()
+      if (fields.trackPageView) {
+        enabledFeatures.push('analytics')
+      }
+    }
+  },
+})
+```

package/docs/configuration/module.md

@@ -0,0 +1,415 @@
+# Module Options
+
+## autoImportPatterns?
+
+> `optional` **autoImportPatterns**: `string`[]
+
+Defined in:
+[options.ts:25](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L25)
+
+File glob patterns for the auto import feature.
+
+If left empty, no documents are auto imported.
+
+### Default
+
+```json
+["**/.{gql,graphql}", "!node_modules"]
+```
+
+### Example
+
+```ts
+// Load .graphql files from pages folder and from a node_modules dependency.
+const autoImportPatterns = [
+  './pages/**/*.graphql',
+  'node_modules/my_library/dist/**/*.graphql',
+]
+```
+
+---
+
+## clientCache?
+
+> `optional` **clientCache**: `object`
+
+Defined in:
+[options.ts:185](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L185)
+
+Client caching configuration.
+
+### enabled?
+
+> `optional` **enabled**: `boolean`
+
+Whether client caching should be enabled.
+
+Note that if you set this to false during build, the cache will not be available
+at all. If you intend to enable/disable it using app config at runtime, it
+_must_ be enabled at build!
+
+##### Default
+
+```ts
+false
+```
+
+### maxSize?
+
+> `optional` **maxSize**: `number`
+
+The maximum number of cache entries.
+
+##### Default
+
+```ts
+100
+```
+
+---
+
+## codegenConfig?
+
+> `optional` **codegenConfig**: `GeneratorOptions`
+
+Defined in:
+[options.ts:142](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L142)
+
+Options for graphql-typescript-deluxe code generator.
+
+### See
+
+[GeneratorOptions](https://github.com/dulnan/graphql-typescript-deluxe/blob/main/src/types/options.ts#L193)
+
+---
+
+## codegenSchemaConfig?
+
+> `optional` **codegenSchemaConfig**: `object`
+
+Defined in:
+[options.ts:147](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L147)
+
+Configuration for graphql-codegen when downloading the schema.
+
+### schemaAstConfig?
+
+> `optional` **schemaAstConfig**: `SchemaASTConfig`
+
+Configure how the schema.graphql file should be generated.
+
+##### See
+
+[SchemaASTConfig](https://github.com/dotansimha/graphql-code-generator/blob/master/packages/plugins/other/schema-ast/src/index.ts#L23)
+
+### urlSchemaOptions?
+
+> `optional` **urlSchemaOptions**: `UrlSchemaOptions`
+
+Configure how the schema-ast introspection request should be made.
+
+Usually this is where you can provide a custom authentication header:
+
+```typescript
+const codegenSchemaConfig = {
+  urlSchemaOptions: {
+    headers: {
+      authentication: 'foobar',
+    },
+  },
+}
+```
+
+##### See
+
+[Types.UrlSchemaOptions](https://github.com/dotansimha/graphql-code-generator/blob/master/packages/utils/plugins-helpers/src/types.ts#L82)
+
+---
+
+## debug?
+
+> `optional` **debug**: `boolean`
+
+Defined in:
+[options.ts:82](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L82)
+
+Enable detailled debugging messages.
+
+### Default
+
+```ts
+false
+```
+
+---
+
+## devtools?
+
+> `optional` **devtools**: `boolean`
+
+Defined in:
+[options.ts:180](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L180)
+
+Enable Nuxt DevTools integration.
+
+### Default
+
+```ts
+true
+```
+
+---
+
+## documents?
+
+> `optional` **documents**: `string`[]
+
+Defined in:
+[options.ts:56](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L56)
+
+Additional raw documents to include.
+
+Useful if for example you need to generate queries during build time.
+
+### Default
+
+```ts
+;[]
+```
+
+### Example
+
+```ts
+const documents = [
+  `
+  query myQuery {
+    articles {
+      title
+      id
+    }
+  }`,
+  ...getGeneratedDocuments(),
+]
+```
+
+---
+
+## downloadSchema?
+
+> `optional` **downloadSchema**: `boolean`
+
+Defined in:
+[options.ts:108](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L108)
+
+Download the GraphQL schema and store it on disk.
+
+Usually you'll want to only enable this during dev mode.
+
+### Default
+
+```ts
+true
+```
+
+---
+
+## enableFileUploads?
+
+> `optional` **enableFileUploads**: `boolean`
+
+Defined in:
+[options.ts:75](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L75)
+
+Enable support for uploading files via GraphQL.
+
+When enabled, an additional `useGraphqlUploadMutation` composable is included,
+in addition to a new server endpoint that handles multi part file uploads for
+GraphQL mutations.
+
+---
+
+## errorOverlay?
+
+> `optional` **errorOverlay**: `boolean`
+
+Defined in:
+[options.ts:87](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L87)
+
+Displays GraphQL response errors in an overlay in dev mode.
+
+---
+
+## experimental?
+
+> `optional` **experimental**: `object`
+
+Defined in:
+[options.ts:208](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L208)
+
+Experimental features.
+
+### improvedQueryParamEncoding?
+
+> `optional` **improvedQueryParamEncoding**: `boolean`
+
+Enables improved encoding for GraphQL query param encoding.
+
+If enabled, query variables that are non-strings such as numbers or booleans are
+encoded as strings, with a prefix in their name to indicate the type.
+
+For example, given this object definining query variables:
+
+```
+{
+  name: 'John',
+  age: 35,
+  isUser: false
+}
+```
+
+This would be encoded as:
+
+```
+name=John&n:age=35&b:isUser=false
+```
+
+This only works for flat primitive values. Nested objects or arrays are still
+encoded using the \_\_variables fallback where all variables are JSON encoded.
+
+---
+
+## graphqlConfigFilePath?
+
+> `optional` **graphqlConfigFilePath**: `string`
+
+Defined in:
+[options.ts:34](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L34)
+
+The path where your graphql.config.ts is, relative to the location of
+nuxt.config.ts.
+
+Used to generate the correct paths in the graphql.config.ts file generated by
+the module.
+
+### Default
+
+```ts
+'./graphql.config.ts'
+```
+
+---
+
+## graphqlEndpoint?
+
+> `optional` **graphqlEndpoint**: `string`
+
+Defined in:
+[options.ts:99](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L99)
+
+The URL of the GraphQL server.
+
+If not provided, the module will use the
+NUXT_GRAPHQL_MIDDLEWARE_GRAPHQL_ENDPOINT environment variable during dev mode.
+
+For the runtime execution you can provide a method that determines the endpoint
+during runtime. See the server/graphqlMiddleware.serverOptions.ts documentation
+for more information.
+
+---
+
+## includeComposables?
+
+> `optional` **includeComposables**: `boolean`
+
+Defined in:
+[options.ts:66](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L66)
+
+Wether the useGraphqlQuery, useGraphqlMutation and useGraphqlState composables
+should be included.
+
+### Default
+
+```ts
+true
+```
+
+---
+
+## logOnlyErrors?
+
+> `optional` **logOnlyErrors**: `boolean`
+
+Defined in:
+[options.ts:135](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L135)
+
+Logs only errors.
+
+When enabled only errors are logged to the console when generating the GraphQL
+operations. If false, all operations are logged, including valid ones.
+
+---
+
+## schemaPath?
+
+> `optional` **schemaPath**: `string`
+
+Defined in:
+[options.ts:118](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L118)
+
+Path to the GraphQL schema file.
+
+If `downloadSchema` is `true`, the downloaded schema is written to this
+specified path. If `downloadSchema` is `false`, this file must be present in
+order to generate types.
+
+### Default
+
+```ts
+'./schema.graphql'
+```
+
+---
+
+## mcp?
+
+> `optional` **mcp**: `object`
+
+Defined in:
+[options.ts:242](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L242)
+
+Configuration for the @nuxtjs/mcp-toolkit integration.
+
+### enabled
+
+> **enabled**: `boolean`
+
+Whether the MCP integration should be enabled.
+
+### route?
+
+> `optional` **route**: `string`
+
+The route of the MCP server.
+
+##### Default
+
+```ts
+'/mcp/nuxt-graphql-middleware'
+```
+
+---
+
+## serverApiPrefix?
+
+> `optional` **serverApiPrefix**: `string`
+
+Defined in:
+[options.ts:127](https://github.com/dulnan/nuxt-graphql-middleware/blob/main/src/build/types/options.ts#L127)
+
+The prefix for the server route.
+
+### Default
+
+```ts
+'/api/graphql_middleware'
+```

package/docs/configuration/runtime-config.md

@@ -0,0 +1,23 @@
+# Runtime Config
+
+The following
+[runtime config](https://nuxt.com/docs/4.x/guide/going-further/runtime-config)
+are provided by the module:
+
+## GraphQL Endpoint
+
+Allows you to set or override the
+[`graphqlEndpoint`](/configuration/module#graphqlendpoint) option.
+
+You can set the GraphQL endpoint to use by setting the
+`NUXT_GRAPHQL_MIDDLEWARE_GRAPHQL_ENDPOINT` environment variable:
+
+```bash
+NUXT_GRAPHQL_MIDDLEWARE_GRAPHQL_ENDPOINT=http://example.com/graphql
+```
+
+This is used to _download the schema_ in **dev mode**. A
+[`graphqlEndpoint`](/configuration/server-options#graphqlendpoint) method
+provided by your server options will take precedence when _making GraphQL
+queries_. If no method exists, then the value of the environment variable is
+also used at runtime (e.g. running the Nuxt build).