{"id":15299,"library":"apollo-server-plugin-query-complexity","title":"Apollo Server Query Complexity Plugin","description":"The `apollo-server-plugin-query-complexity` package provides a plugin for `@apollo/server` to enforce query complexity limits, safeguarding against overly resource-intensive queries. It is currently at version 4.0.0, aligning with `@apollo/server` v4.x. This plugin differentiates itself by being fully compatible with GraphQL operation variables, a feature that standard `graphql-js` validation rules cannot directly access when integrated with Apollo Server. It leverages `graphql-query-complexity` for its core estimation logic, supporting various estimators like `directiveEstimator` and `simpleEstimator`, which allow developers to define complexity values directly within their schema or through default calculation rules. This mechanism is crucial for preventing denial-of-service attacks by ensuring server stability and fair resource allocation. The project appears actively maintained, with releases typically synchronized with major `@apollo/server` versions.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/nvdaz/apollo-server-plugin-query-complexity","tags":["javascript","typescript"],"install":[{"cmd":"npm install apollo-server-plugin-query-complexity","lang":"bash","label":"npm"},{"cmd":"yarn add apollo-server-plugin-query-complexity","lang":"bash","label":"yarn"},{"cmd":"pnpm add apollo-server-plugin-query-complexity","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the core Apollo Server framework that the plugin integrates with.","package":"@apollo/server","optional":false},{"reason":"The underlying GraphQL.js library, essential for schema parsing and query validation.","package":"graphql","optional":false},{"reason":"Provides the core logic and estimators for calculating GraphQL query complexity.","package":"graphql-query-complexity","optional":false}],"imports":[{"note":"The primary default export for the plugin factory. Primarily designed for ESM usage with Apollo Server v4.","wrong":"const ApolloServerPluginQueryComplexity = require('apollo-server-plugin-query-complexity');","symbol":"ApolloServerPluginQueryComplexity","correct":"import ApolloServerPluginQueryComplexity from 'apollo-server-plugin-query-complexity';"},{"note":"Named export for the custom error type, useful for distinguishing complexity errors in custom error formatting.","symbol":"QueryComplexityError","correct":"import { QueryComplexityError } from 'apollo-server-plugin-query-complexity';"},{"note":"These estimators are sourced directly from the `graphql-query-complexity` peer dependency, not from this plugin package itself.","wrong":"import { directiveEstimator, simpleEstimator } from 'apollo-server-plugin-query-complexity';","symbol":"directiveEstimator, simpleEstimator","correct":"import { directiveEstimator, simpleEstimator } from 'graphql-query-complexity';"}],"quickstart":{"code":"import { ApolloServer } from '@apollo/server';\nimport ApolloServerPluginQueryComplexity from 'apollo-server-plugin-query-complexity';\nimport { directiveEstimator, simpleEstimator } from 'graphql-query-complexity';\n\nconst typeDefs = `#graphql\n  directive @complexity(\n    value: Int!\n    multipliers: [String!]\n  ) on FIELD_DEFINITION\n\n  type Query {\n    a: String! # Complexity of 1\n    b(n: Int!): String! @complexity(value: 1, multipliers: [\"n\"]) # Complexity of variable \"n\"\n  }\n`;\n\nconst server = new ApolloServer({\n  typeDefs,\n  resolvers: {},\n  plugins: [\n    ApolloServerPluginQueryComplexity({\n      estimators: [directiveEstimator(), simpleEstimator()],\n      maximumComplexity: 100,\n    }),\n  ],\n});\n\n// Example of starting the server (assuming a basic setup, e.g., for testing)\n// This part is illustrative and depends on your Apollo Server integration (e.g., Express, standalone)\nasync function startApolloServer() {\n  // In a real application, you'd likely use startStandaloneServer or integrate with a web framework\n  // For demonstration, let's just log that the server is configured\n  console.log('Apollo Server configured with Query Complexity Plugin.');\n  console.log('Maximum complexity set to 100.');\n}\n\nstartApolloServer();","lang":"typescript","description":"Demonstrates how to integrate the query complexity plugin into an Apollo Server instance with directive-based and simple complexity estimators, setting a maximum complexity limit."},"warnings":[{"fix":"Ensure your project's `@apollo/server` and `graphql` dependencies are upgraded to their respective v4 and v16 versions, respectively, before installing `apollo-server-plugin-query-complexity@4.x`.","message":"Version 4.x of `apollo-server-plugin-query-complexity` is designed exclusively for `@apollo/server` v4.x and `graphql` v16.x. Attempting to use this plugin version with older Apollo Server (e.g., `apollo-server` v3.x or `apollo-server-express` v3.x) will lead to runtime errors due to fundamental changes in Apollo Server's plugin API.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Add a `formatError` option to your `ApolloServer` constructor that checks if `error instanceof QueryComplexityError` and returns a custom formatted error object.","message":"The default error message for queries exceeding the complexity limit can be generic. For a better user experience, it's highly recommended to implement a custom `formatError` function in your `ApolloServer` configuration to catch `QueryComplexityError` and provide more descriptive feedback, including the requested and maximum complexity values.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully review your `estimators` array in the `ApolloServerPluginQueryComplexity` configuration. Ensure `directiveEstimator()` is included if using `@complexity` directives, and consider `simpleEstimator()` as a fallback or default for fields without explicit directives.","message":"Misconfiguring complexity estimators can either render the plugin ineffective (allowing overly complex queries) or too restrictive (rejecting legitimate queries). Ensure all fields in your schema have a valid complexity estimation strategy, combining `directiveEstimator` for annotated fields and `simpleEstimator` or custom estimators for unannotated fields.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always install `graphql-query-complexity` alongside `apollo-server-plugin-query-complexity`: `npm install graphql-query-complexity` or `yarn add graphql-query-complexity`.","message":"`apollo-server-plugin-query-complexity` lists `graphql-query-complexity` as a peer dependency, meaning it must be installed separately by the user. Forgetting to install `graphql-query-complexity` will result in runtime errors as the plugin won't find its essential estimation logic.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Either optimize the client-side query to reduce its complexity, or adjust the `maximumComplexity` setting in your `ApolloServerPluginQueryComplexity` configuration if the current limit is too strict for intended use cases. Review your complexity estimators for accuracy.","cause":"The calculated complexity of a GraphQL query, based on the plugin's estimators, exceeded the `maximumComplexity` defined in the plugin configuration.","error":"message: \"Query is too complex. Requested complexity XXX is greater than maximum allowed YYY.\""},{"fix":"Install the missing peer dependencies using your package manager, ensuring their versions meet the requirements specified by `apollo-server-plugin-query-complexity@4.x`: `npm install @apollo/server@^4.0.0 graphql@^16.6.0 graphql-query-complexity@^0.12.0`.","cause":"One or more of the required peer dependencies (`@apollo/server`, `graphql`, or `graphql-query-complexity`) are not installed in the project or are installed with an incompatible version.","error":"Error: Cannot find module '@apollo/server' or Error: Cannot find module 'graphql-query-complexity'"}],"ecosystem":"npm"}