nuxt-graphql-middleware 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -1,27 +1,21 @@
-# Nuxt GraphQL Middleware
+![nuxt-graphql-middleware banner](docs/banner.png?raw=true "Nuxt GraphQL Middleware - Expose queries and mutations as fully typed API routes.")
 
-GraphQL in the backend, fetch in the frontend. With TypeScript support.
+# Nuxt GraphQL Middleware
 
-## Idea
-When using GraphQL you have to bundle your queries in your frontend build and
-send them with every request. If you have lots of queries and/or fragments,
-this can increase your frontend bundle size significantly. In addition you have
-to expose your entire GraphQL endpoint to the public (if you don't use persisted
-queries).
+Expose GraphQL queries and mutations as fully typed API routes.
 
-This module aims to fix this by performing any GraphQL requests only on the
-server side. It passes the response to the frontend via a simple JSON endpoint.
-So you can have all the benefits of GraphQL but without any bloat.
+**[Documentation](https://nuxt-graphql-middleware.dulnan.net)** – **[npm](https://www.npmjs.com/package/nuxt-graphql-middleware)** – **[Version 2.x (for Nuxt 2)](https://github.com/dulnan/nuxt-graphql-middleware/tree/2.x)**
 
-It optionally generates TypeScript type files of your schema, queries and
-mutations via [graphql-codegen](https://github.com/dotansimha/graphql-code-generator).
+[![Test](https://github.com/dulnan/nuxt-graphql-middleware/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/dulnan/nuxt-graphql-middleware/actions/workflows/node.js.yml)
 
 ## Features
-- GraphQL queries and mutations using graphql-request
-- Client plugin to perform queries or mutations
-- Fully flexible: Modify request headers, responses or handle errors
-- HMR for queries and mutations
-- TypeScript integration for schema, queries and mutations
+- Exposes each query and mutation as an API route
+- GraphQL requests are only done on the server side
+- No GraphQL documents in client bundle
+- Includes composables to perform queries or mutations
+- Modify request headers, responses and handle errors
+- HMR for all GraphQL files
+- Full TypeScript integration for schema, queries, mutations and fragments using [graphql-code-generator](https://github.com/dotansimha/graphql-code-generator)
 
 # Setup
 
@@ -32,333 +26,35 @@ npm install --save nuxt-graphql-middleware
 
 Minimal configuration needed:
 ```javascript
-module.exports = {
+export default defineNuxtConfig({
   modules: ['nuxt-graphql-middleware'],
   graphqlMiddleware: {
-    graphqlServer: 'http://example.com/graphql',
-    typescript: {
-      enabled: true
-    },
-    queries: {
-      articles: '~/pages/query.articles.graphql',
-    },
-    plugin: {
-      enabled: true
-    }
+    graphqlEndpoint: 'https://example.com/graphql',
   }
-}
-```
-
-# Usage
-
-## With provided plugin
-
-### Simple query
-```javascript
-asyncData({ app }) {
-  return app.$graphql.query('articles').then(data => {
-    return { articles: data.articles }
-  })
-}
-```
-
-### With variables
-
-Anything you provide in the second argument will be passed 1:1 as variables to
-the GraphQL request.
-
-```javascript
-asyncData({ app }) {
-  return app.$graphql.query('articles', { limit: 10 }).then(data => {
-    return { articles: data.articles }
-  })
-}
-```
-
-### Simple mutation
-
-Anything you provide in the second argument is used as the mutation input.
-```javascript
-createPost(post) {
-  return app.$graphql.mutate('createPost', post).then(response => {
-    if (response.hasError) {
-      this.errors.push(response.error)
-    }
-  })
-}
-```
-
-## Custom requests
-
-You can do your own requests without using the plugin.
-Query variables are passed as a JSON encoded string.
-
-```javascript
-fetch('/__api/query?name=articles')
-fetch('/__api/query?name=articles&variables={"limit":10}')
-fetch('/__api/mutate?name=createPost', {
-  method: 'POST',
-  body: JSON.stringify(post)
 })
 ```
 
+## Usage
 
-# Configuration
-
-## Options
-
-### graphqlServer: string
-URL of your GraphQL server.
-
-### endpointNamespace: string
-
-Namespace where the server middleware is running, e.g. '/__api'.
-=> http://localhost:3000/__api/query
-
-### debug: boolean
-Output additional info about available queries and mutations to the console.
-
-### queries: Record<string, string>
-Map of query name => filePath.
-
-### mutations: Record<string, string>
-Map of mutation name => filePath.
-
-### outputPath: string
-If set, the module will write the compiled queries and mutations in this
-folder.
-
-### plugin.enabled: boolean
-Enable the helper plugin.
-
-### plugin.cacheInBrowser: boolean
-Cache requests in the plugin (on client side / browser).
-
-This enables a simple cache (using a Map) in the browser, which will cache up
-to 30 queries. This is useful to provide near instant rendering when going back
-and forth in the browser history.
-
-Queries are cached based on their full URL (incl. query string).
-
-### plugin.cacheInServer: boolean
-Same as cacheInBrowser, but the queries are also cached server side.
-*Note:* There is no way to purge this cache! Only use this if you're fine with
-returning potentially outdated responses.
-
-### server.middleware: (req: Request, res: Response, next: NextFunction) => any
-An express middleware. Can be used for example to add an authentication or CORS
-check.
-
-```javascript
-function(req, res, next) {
-  if (isLoggedIn(req.headers.cookie)) {
-    return next()
-  }
-  res.status(403).send()
-}
-```
-
-### server.fetchOptions: Record<string, any>
-Object of options passed to the fetch request to GraphQL.
-
-### server.buildHeaders: (req: Request, name: string, type: string) => Record<string, any>
-Called before every request
-
-```javascript
-function (req, name, type) {
-  if (isLoggedIn(req.headers.cookie)) {
-    if (type === 'mutation') {
-      return {
-        Authorization: 'Basic ' + process.env.BASIC_AUTH_WRITE
-      }
-    }
-  }
-}
-```
-
-### server.buildEndpoint: (req: Request) => string
-Called before every request. This allows you to set the URL for the GraphQL
-server.
-
-This is useful if you have multiple endpoints, for example with a language
-prefix.
-
-```javascript
-function (req) {
-  const language = getLanguageFromHeaders(req.headers)
-  return `https://example.com/${language}/graphql`
-}
-```
-
-
-### server.onQueryResponse: (response: GraphQLResponse, req: Request, res: Response) => any
-Handle GraphQL server query responses before they are sent to the client.
-
-```javascript
-function(response, req, res) {
-  return res.json({
-    data: response.data,
-    time: Date.now()
-  })
-}
-```
-
-### server.onQueryError: (error: ClientError, req: Request, res: Response) => any
-Handle GraphQL server query errors before they are sent to the client.
-
-### server.onMutationResponse: (response: GraphQLResponse, req: Request, res: Response) => any
-Handle GraphQL server mutation responses before they are sent to the client.
-
-### server.onMutationError: (error: ClientError, req: Request, res: Response) => any
-Handle GraphQL server mutation errors before they are sent to the client.
-
-### typescript.enabled: boolean
-Enable TypeScript integration.
-
-### typescript.schemaOutputPath: string
-Folder where the downloaded schema.graphql file is saved.
-
-### typescript.skipSchemaDownload: boolean
-Don't download the schema. Use this for example if you commit the schema in
-your repository, so that it's available during deployment.
-
-### typescript.schemaOptions: [UrlSchemaOptions](https://github.com/dotansimha/graphql-code-generator/blob/master/packages/utils/plugins-helpers/src/types.ts#L74)
-Options passed to graphql-codegen.
-
-### typescript.typesOutputPath: string
-Folder where the generated graphql-schema.d.ts and graphql-operations.d.ts
-files are saved.
-
-## Extend $graphql plugin
-
-If you want to add custom headers to the request made by `$graphql` to the
-middleware, create a plugin and add a `beforeRequest` method:
-
-```javascript
-export default (pluginContext) => {
-  pluginContext.$graphql.beforeRequest((ctx, options) => {
-    options.headers['accept-language'] = ctx.route.params.lang
-    return options
-  })
-}
-```
-
-You have access to the context via the first parameter. The second parameter
-provides the fetch options, which you have to return.
-
-It's also possible to return a Promise, useful if you need to handle things
-like a token refresh. Be aware that this method is called before every query or
-mutation request, so make sure it doesn't take too much time.
+Write your first query, e.g. in pages/films.query.graphql:
 
-
-### Integrate with nuxt-auth
-
-Add a `beforeRequest` method in a custom plugin:
-
-```javascript
-export default (pluginContext) => {
-  pluginContext.$graphql.beforeRequest((ctx, options) => {
-    if (ctx.$auth.loggedIn) {
-      options.headers['authorization'] = ctx.$auth.strategy.token.get()
-    }
-    return options
-  })
-}
-```
-
-Add a `server.buildHeaders` method, where you get the authorization header from
-the client request and pass it on to the server request.
-
-```javascript
-buildHeaders(req, name, type) {
-  const auth = req.headers.authorization
-  if (auth) {
-    return {
-      Authorization: auth,
+```graphql
+query films {
+  allFilms {
+    films {
+      id
     }
   }
-
-  return {}
 }
 ```
 
-## Full working example
-
-```javascript
-module.exports = {
-  modules: ['nuxt-graphql-middleware'],
+Your query is now available via the useGraphqlQuery() composable:
 
-  graphqlMiddleware: {
-    graphqlServer: 'http://example.com/graphql'
-    endpointNamespace: '/__api'
-    debug: true
-    queries: {
-      route: '~/pages/query.route.graphql',
-      articles: '~/pages/articles/query.articles.graphql',
-      footer: '~/components/Footer/query.footer.graphql',
-    },
-    mutations: {
-      createPost: '~/components/Comment/mutation.createPost.graphql'
-    },
-    outputPath: '~/graphql_tmp'
-    plugin: {
-      enabled: true,
-      cacheInBrowser: true,
-      cacheInServer: false,
-    },
-    typescript: {
-      enabled: true,
-      schemaOutputPath: '~/schema',
-      typesOutputPath: '~/types',
-      schemaOptions: {
-        headers: {
-          Authorization: 'Basic ' + process.env.BASIC_AUTH
-        }
-      }
-    },
-    server: {
-      middleware: function(req, res, next) {
-        if (isLoggedIn(req.headers.cookie)) {
-          return next()
-        }
-        res.status(403).send()
-      },
-      fetchOptions: {
-        headers: {
-          Authorization: 'Basic ' + process.env.BASIC_AUTH
-        }
-      },
-      buildHeaders: function (req, name, type) {
-        if (isLoggedIn(req.headers.cookie)) {
-          if (type === 'mutation') {
-            return {
-              Authorization: 'Basic ' + process.env.BASIC_AUTH_WRITE
-            }
-          }
-        }
-      },
-      onQueryResponse: function(response, req, res) {
-        return res.json({
-          data: response.data,
-          time: Date.now()
-        })
-      },
-      onQueryError: function(error, req, res) {
-        return res.status(500).send()
-      },
-      onMutationResponse: function(response, req, res) {
-        return res.json({
-          data: response.data,
-          time: Date.now()
-        })
-      }
-      onMutationError: function(error, req, res) {
-        return res.status(500).send()
-      }
-    }
-  }
-}
+```typescript
+const { data } = await useGraphqlQuery('films')
+console.log(data.allFilms.films)
 ```
 
-# TODO
-- Pass port to client plugin
+Alternatively you can also call
+`http://localhost:3000/api/graphql_middleware/query/films` to get the same
+result.

package/dist/module.d.ts

@@ -1,12 +1,209 @@
-declare module '@nuxt/schema' {
-  interface RuntimeConfig {
-    graphqlMiddleware: {
-      rootDir: string
-    }
-    public: {
-      'nuxt-graphql-middleware': {
-        serverApiPrefix: string
-      }
-    }
-  }
+import { NuxtModule } from '@nuxt/schema';
+import { H3Event } from 'h3';
+import { FetchOptions, FetchResponse, FetchError } from 'ofetch';
+import { TypeScriptDocumentsPluginConfig } from '@graphql-codegen/typescript-operations';
+
+type GraphqlMiddlewareGraphqlEndpointMethod = (event?: H3Event, operation?: string, operationName?: string) => string;
+type GraphqlMiddlewareServerFetchOptionsMethod = (event?: H3Event, operation?: string, operationName?: string) => FetchOptions;
+type GraphqlMiddlewareOnServerResponseMethod = (event: H3Event, response: FetchResponse<any>, operation?: string, operationName?: string) => any;
+type GraphqlMiddlewareOnServerErrorMethod = (event: H3Event, error: FetchError, operation?: string, operationName?: string) => any;
+interface GraphqlMiddlewareConfig {
+    /**
+     * 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'
+     * ]
+     * ```
+     */
+    autoImportPatterns?: string[];
+    /**
+     * Additional raw documents to include.
+     *
+     * Useful if for example you need to generate queries during build time.
+     *
+     * @default []
+     *
+     * @example
+     * ```ts
+     * const documents = [`
+     *   query myQuery {
+     *     articles {
+     *       title
+     *       id
+     *     }
+     *   }`,
+     *   ...getGeneratedDocuments()
+     * ]
+     * ```
+     */
+    documents?: string[];
+    /**
+     * Wether the useGraphqlQuery, useGraphqlMutation and useGraphqlState
+     * composables should be included.
+     *
+     * @default ```ts
+     * true
+     * ```
+     */
+    includeComposables?: boolean;
+    /**
+     * Enable detailled debugging messages.
+     *
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * The URL of the GraphQL server.
+     *
+     * You can either provide a string or a method that returns a string.
+     * If you provide a method it will be called everytime a GraphQL request is
+     * made in the server API handler.
+     *
+     * @example
+     * ```ts
+     * function graphqlEndpoint(event, operation, operationName) {
+     *   const language = getLanguageFromRequest(event)
+     *   return `https://api.example.com/${language}/graphql`
+     * }
+     * ```
+     */
+    graphqlEndpoint?: string | GraphqlMiddlewareGraphqlEndpointMethod;
+    /**
+     * The prefix for the server route.
+     *
+     * @default ```ts
+     * "/api/graphql_middleware"
+     * ```
+     */
+    serverApiPrefix?: string;
+    /**
+     * Provide the options for the ofetch request to the GraphQL server.
+     *
+     * @default undefined
+     *
+     * @example
+     * ```ts
+     * import { getHeader } from 'h3'
+     *
+     * // Pass the cookie from the client request to the GraphQL request.
+     * function serverFetchOptions(event, operation, operationName) {
+     *   return {
+     *     headers: {
+     *       Cookie: getHeader(event, 'cookie')
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    serverFetchOptions?: FetchOptions | GraphqlMiddlewareServerFetchOptionsMethod;
+    /**
+     * Handle the response from the GraphQL server.
+     *
+     * You can alter the response, add additional properties to the data, get
+     * and set headers, etc.
+     *
+     * ```ts
+     * import type { H3Event } from 'h3'
+     * import type { FetchResponse } from 'ofetch'
+     *
+     * function onServerResponse(event: H3Event, graphqlResponse: FetchResponse) {
+     *   // Set a static header.
+     *   event.node.res.setHeader('x-nuxt-custom-header', 'A custom header value')
+     *
+     *   // Pass the set-cookie header from the GraphQL response to the client.
+     *   const setCookie = graphqlResponse.headers.get('set-cookie')
+     *   if (setCookie) {
+     *     event.node.res.setHeader('set-cookie', setCookie)
+     *   }
+     *
+     *   // Add additional properties to the response.
+     *   graphqlResponse._data.__customProperty = ['My', 'values']
+     *
+     *   // Return the GraphQL response.
+     *   return graphqlResponse._data
+     * }
+     * ```
+     */
+    onServerResponse?: GraphqlMiddlewareOnServerResponseMethod;
+    /**
+     * Handle a fetch error from the GraphQL request.
+     *
+     * Note that errors are only thrown for responses that are not status
+     * 200-299. See https://github.com/unjs/ofetch#%EF%B8%8F-handling-errors for
+     * more information.
+     *
+     * ```ts
+     * import { createError } from 'h3'
+     * import type { H3Event } from 'h3'
+     * import type { FetchError } from 'ofetch'
+     *
+     * function onServerError(
+     *   event: H3Event,
+     *   error: FetchError,
+     *   operation: string,
+     *   operationName: string,
+     * ) {
+     *   // Throw a h3 error.
+     *   throw createError({
+     *     statusCode: 500,
+     *     statusMessage: `Couldn't execute GraphQL ${operation} "${operationName}".`,
+     *     data: error.message
+     *   })
+     * }
+     * ```
+     */
+    onServerError?: GraphqlMiddlewareOnServerErrorMethod;
+    /**
+     * Download the GraphQL schema and store it in the
+     *
+     * @default true
+     */
+    downloadSchema?: boolean;
+    /**
+     * 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 './schema.graphql'
+     */
+    schemaPath?: string;
+    /**
+     * These options are passed to the graphql-codegen method when generating the operations types.
+     *
+     * {@link https://www.the-guild.dev/graphql/codegen/plugins/typescript/typescript-operations}
+     * @default
+     * ```ts
+     * const codegenConfig = {
+     *   exportFragmentSpreadSubTypes: true,
+     *   preResolveTypes: true,
+     *   skipTypeNameForRoot: true,
+     *   skipTypename: true,
+     *   useTypeImports: true,
+     *   onlyOperationTypes: true,
+     *   namingConvention: {
+     *     enumValues: 'change-case-all#upperCaseFirst',
+     *   },
+     * }
+     * ```
+     */
+    codegenConfig?: TypeScriptDocumentsPluginConfig;
 }
+
+type ModuleOptions = GraphqlMiddlewareConfig;
+type ModuleHooks = {};
+declare const _default: NuxtModule<GraphqlMiddlewareConfig>;
+
+export { ModuleHooks, ModuleOptions, _default as default };

package/dist/module.json

@@ -1,5 +1,8 @@
 {
   "name": "nuxt-graphql-middleware",
   "configKey": "graphqlMiddleware",
-  "version": "3.0.0-beta.1"
+  "version": "3.0.0-beta.3",
+  "compatibility": {
+    "nuxt": "^3.0.0"
+  }
 }