@apollo/server@4.0.0
BREAKING CHANGES
Apollo Server contains quite a few breaking changes: most notably, a brand new package name! Read our migration guide for more details on how to update your app.
Bumped dependencies
The minimum versions of these dependencies have been bumped to provide an improved foundation for the development of future features.
- Dropped support for Node.js v12, which is no longer under long-term support from the Node.js Foundation.
- Dropped support for versions of the
graphql
library prior tov16.6.0
.- Upgrading
graphql
may require you to upgrade other libraries that are installed in your project. For example, if you use Apollo Server with Apollo Gateway, you should upgrade Apollo Gateway to at least v0.50.1 or any v2.x version for fullgraphql
16 support before upgrading to Apollo Server 4.
- Upgrading
- If you use Apollo Server with TypeScript, you must use TypeScript v4.7.0 or newer.
New package structure
Apollo Server 4 is distributed in the @apollo/server
package. This package replaces apollo-server
, apollo-server-core
, apollo-server-express
, apollo-server-errors
, apollo-server-types
, and apollo-server-plugin-base
.
The @apollo/server
package exports the ApolloServer
class. In Apollo Server 3, individual web framework integrations had their own subclasses of ApolloServer
. In Apollo Server 4, there is a single ApolloServer
class; web framework integrations define their own functions which use a new stable integration API on ApolloServer
to execute operations.
Other functionality is exported from "deep imports" on @apollo/server
. startStandaloneServer
(the replacement for the batteries-included apollo-server
package) is exported from @apollo/server/standalone
. expressMiddleware
(the replacement for apollo-server-express
) is exported from @apollo/server/express4
. Plugins such as ApolloServerPluginUsageReporting
are exported from paths such as @apollo/server/plugin/usageReporting
.
The @apollo/server
package is built natively as both an ECMAScript Module (ESM) and as a CommonJS module (CJS); Apollo Server 3 was only built as CJS. This allows ESM-native bundlers to create more efficient bundles.
Other packages have been renamed:
apollo-datasource-rest
is now@apollo/datasource-rest
.apollo-server-plugin-response-cache
is now@apollo/server-plugin-response-cache
.apollo-server-plugin-operation-registry
is now@apollo/server-plugin-operation-registry
.apollo-reporting-protobuf
(an internal implementation detail for the usage reporting plugin) is now@apollo/usage-reporting-protobuf
.
Removed web framework integrations
Prior to Apollo Server 4, the only way to integrate a web framework with Apollo Server was for the Apollo Server project to add an official apollo-server-x
subclass maintained as part of the core project. Apollo Server 4 makes it easy for users to integrate with their favorite web framework, and so we have removed most of the framework integrations from the core project so that framework integrations can be maintained by users who are passionate about that framework. Because of this, the core project no longer directly maintains integrations for Fastify, Hapi, Koa, Micro, AWS Lambda,Google Cloud Functions, Azure Functions, or Cloudflare. We expect that community integrations will eventually be created for most of these frameworks and serverless environments.
Apollo Server's support for the Express web framework no longer also supports its older predecessor Connect.
Removed constructor options
- The
dataSources
constructor option essentially added a post-processing step to your app's context function, creatingDataSource
subclasses and adding them to adataSources
field on your context value. This meant the TypeScript type thecontext
function returns was different from the context type your resolvers and plugins receive. Additionally, this design obfuscated thatDataSource
objects are created once per request (i.e., like the rest of the context object). Apollo Server 4 removes thedataSources
constructor option. You can now treatDataSources
like any other part of yourcontext
object. See the migration guide for details on how to move yourdataSources
function into yourcontext
function. - The
modules
constructor option was just a slightly different way of writingtypeDefs
andresolvers
(although it surprisingly used entirely different logic under the hood). This option has been removed. - The
mocks
andmockEntireSchema
constructor options wrapped an outdated version of the@graphql-tools/mocks
library to provide mocking functionality. These constructor options have been removed; you can instead directly incorporate the@graphql-tools/mock
package into your app, enabling you to get the most up-to-date mocking features. - The
debug
constructor option (which defaulted totrue
unless theNODE_ENV
environment variable is eitherproduction
ortest
) mostly controlled whether GraphQL errors responses included stack traces, but it also affected the default log level on the default logger. Thedebug
constructor option has been removed and is replaced withincludeStacktraceInErrorResponses
, which does exactly what it says it does. - The
formatResponse
constructor option has been removed; its functionality can be replaced by thewillSendResponse
plugin hook. - The
executor
constructor option has been removed; the ability to replacegraphql-js
's execution functionality is still available via thegateway
option.
Removed features
- Apollo Server 4 no longer responds to health checks on the path
/.well-known/apollo/server-health
. You can run a trivial GraphQL operation as a health check, or you can add a custom health check via your web framework. - Apollo Server 4 no longer cares what URL path is used to access its functionality. Instead of specifying the
path
option to various Apollo Server methods, just use your web framework's routing feature to mount the Apollo Server integration at the appropriate path. - Apollo Server 4's Express middleware no longer wraps the
body-parser
andcors
middleware; it is your responsibility to install and set up these middleware yourself when using a framework integration. (The standalone HTTP server sets up body parsing and CORS for you, but without the ability to configure their details.) - Apollo Server no longer re-exports the
gql
tag function fromgraphql-tag
. If you want to usegql
, install thegraphql-tag
package. - Apollo Server no longer defines its own
ApolloError
class andtoApolloError
function. Instead, useGraphQLError
from thegraphql
package. - Apollo Server no longer exports error subclasses representing the errors that it creates, such as
SyntaxError
. Instead, it exports an enumApolloServerErrorCode
that you can use to recognize errors created by Apollo Server. - Apollo Server no longer exports the
ForbiddenError
andAuthenticationError
classes. Instead, you can define your own error codes for these errors or other errors. - The undocumented
__resolveObject
pseudo-resolver is no longer supported. - The
requestAgent
option toApolloServerPluginUsageReporting
has been removed. - In the JSON body of a
POST
request, thevariables
andextensions
fields must be objects, not JSON-encoded strings. - The core Apollo Server packages no longer provide a landing page plugin for the unmaintained GraphQL Playground UI. We have published an Apollo Server 4-compatible landing page plugin in the package
@apollo/server-plugin-landing-page-graphql-playground
, but do not intend to maintain it further after this one-time publish.
Modified functionality
- The
context
function is now provided to your integration function (such asstartStandaloneServer
orexpressMiddleware
) rather than to thenew ApolloServer
constructor. - The
executeOperation
method now directly accepts a context value, rather than accepting the arguments to yourcontext
function. - The
formatError
hook now receives the original thrown error in addition to the formatted error. - Formatted errors no longer contain the
extensions.exception
field containing all enumerable properties of the originally thrown error. If you want to include more information in an error, specify them asextensions
when creating aGraphQLError
. Thestacktrace
field is provided directly onextensions
rather than nested underexception
. - All errors responses are consistently rendered as
application/json
JSON responses, and theformatError
hook is used consistently. - Other changes to error handling outside of resolvers are described in the migration guide.
- The
parseOptions
constructor option only affects the parsing of incoming operations, not the parsing oftypeDefs
.
Plugin API changes
- The field
GraphQLRequestContext.context
has been renamed tocontextValue
. - The field
GraphQLRequestContext.logger
is now readonly. - The fields
GraphQLRequestContext.schemaHash
andGraphQLRequestContext.debug
have been removed. - The type
GraphQLServiceContext
has been renamed toGraphQLServerContext
, and the fieldsschemaHash
,persistedQueries
, andserverlessFramework
have been removed; the latter has been semi-replaced bystartedInBackground
. - The
http
field on theGraphQLRequest
object (available to plugins asrequestContext.request
and as an argument toserver.executeOperation
) is no longer based on the Fetch API'sRequest
object. It no longer contains an URL path, and itsheaders
field is aMap
rather than aHeaders
object. - The structure of the
GraphQLResponse
object (available to plugins asrequestContext.response
and as the return value fromserver.executeOperation
) has changed in several ways. - The
plugins
constructor argument does not take factory functions. requestDidStart
hooks are called in parallel rather than in series.- A few changes have been made which may affect custom
gateway
andGraphQLDataSource
implementations.
Changes to defaults
- CSRF prevention is on by default.
- HTTP batching is disabled by default.
- The default in-memory cache is bounded.
- The local landing page defaults to the embedded Apollo Sandbox; this provides a user interface for executing GraphQL operations which doesn't require any additional CORS configuration.
- The usage reporting and inline trace plugins mask errors in their reports by default: error messages are replaced with
<masked>
and error extensions are replaced with a single extensionmaskedBy
. This can be configured with thesendErrors
option toApolloServerPluginUsageReporting
and theincludeErrors
option toApolloServerPluginInlineTrace
. TherewriteError
option to these plugins has been removed; its functionality is subsumed by the new options.
TypeScript-specific changes
- The TypeScript types for the
validationRules
constructor option are more accurate. - We now use the
@apollo/utils.fetcher
package to define the shape of the Fetch API, instead ofapollo-server-env
. This package only supports argument structures that are likely to be compatible across implementations of the Fetch API. - The
CacheScope
,CacheHint
,CacheAnnotation
,CachePolicy
, andResolveInfoCacheControl
types are now exported from the@apollo/cache-control-types
package.CacheScope
is now a pure TypeScript type rather than an enum. - The type for
ApolloServer
's constructor options argument is nowApolloServerOptions
, notConfig
orApolloServerExpressConfig
. - Some other types have been renamed or removed; see the migration guide for details.
New features
- In TypeScript, you can now declare your server's context value type using generic type syntax, like
new ApolloServer<MyContextType>
. This ensures that the type returned by your context function matches the context type provided to your resolvers and plugins. ApolloServer
now has a well-documented API for integrating with web frameworks, featuring the newexecuteHTTPGraphQLRequest
method.ApolloServer
now has explicit support for the "serverless" style of startup error handling. Serverless frameworks generally do not allow handlers to do "async" work during startup, so any failure to load the schema or runserverWillStart
handlers can't prevent requests from being served. Apollo Server 4 provides aserver.startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests()
method as an alternative toawait server.start()
for use in contexts like serverless environments.- You can add a plugin to a server with
server.addPlugin()
. Plugins can only be added before the server isstart
ed. This allows you to pass the server itself as an argument to the plugin. ApolloServer
has new public readonlycache
andlogger
fields.- When combined with
graphql
v17 (only available as pre-releases as of September 2022), Apollo Server now has experimental support for incremental delivery directives such as@defer
and@stream
. - Apollo Server 4 adds new plugin hooks
startupDidFail
,contextCreationDidFail
,invalidRequestWasReceived
,unexpectedErrorProcessingRequest
,didEncounterSubsequentErrors
, andwillSendSubsequentPayload
. - If Apollo Server receives an operation while the server is shutting down, it now logs a warning telling you to properly configure HTTP server draining.
- Apollo Server now supports responses with
content-type: application/graphql-response+json
when requested by clients via theaccept
header, as described in the GraphQL over HTTP specification proposal.