docs: support Express v5, recommend new separate Express packages (#8064)

The built-in `expressMiddleware` in `@apollo/server/express4` only
supports Express v4, and that's not going to change. But Express v5 is
now released.

So we have released separate packages `@as-integrations/express4` and
`@as-integrations/express5`. The next major version of Apollo Server
will drop the hard-coded built-in integrations, putting all JS web
frameworks on the same playing field where you have to install a small
integration package to use it.

This PR:
- Documents that the two new packages exist (and that the old export
does still work)
- Changes most examples to use the new Express v5 integration
- Changes the AS3 to AS4 migration guide to use the new Express v4
integration (assuming that anyone migrating from AS3 is not on the
brand-new version of Express)

Fixes #7928.

---------

Co-authored-by: Maria Elisabeth Schreiber <maria.schreiber@apollographql.com>

Author: glasser

.changeset/stupid-insects-love.md

@@ -0,0 +1,5 @@
+---
+'@apollo/server': patch
+---
+
+Update README.md to recommend Express v5 integration now that Express v5 is released.

docs/source/api/express-middleware.mdx

@@ -7,6 +7,18 @@ import TopLevelAwait from "../shared/top-level-await.mdx"
 
 This API reference documents Apollo Server 4's [Express](https://expressjs.com/) integration, the `expressMiddleware` function.
 
+Apollo Server integrates with these Express versions through official integrations:
+- [**Express v4**](https://www.npmjs.com/package/@as-integrations/express4): Install with `npm install @as-integrations/express4`
+- [**Express v5**](https://www.npmjs.com/package/@as-integrations/express5): Install with `npm install @as-integrations/express5`
+
+You must also install Express itself. Both packages export a function named `expressMiddleware` with the same API.
+
+<Note>
+
+The Express v4 integration is also bundled in `@apollo/server` at `@apollo/server/express4`. While you can use this bundled version now, we recommend installing the separate package. Express v5 requires the separate package, and future Apollo Server versions will remove the bundled integration.
+
+</Note>
+
 ## `expressMiddleware`
 
 <TopLevelAwait />
@@ -23,7 +35,7 @@ The `expressMiddleware` function accepts two arguments. The first **required** a
 
 ```ts
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
+import { expressMiddleware } from '@as-integrations/express5';
 import cors from 'cors';
 import express from 'express';
 
@@ -95,10 +107,10 @@ Below is a full example of setting up `expressMiddleware`:
 <MultiCodeBlock>
 
 ```ts
-// npm install @apollo/server express graphql cors
+// npm install @apollo/server @as-integrations/express5 express graphql cors
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import { expressMiddleware } from '@as-integrations/express5';
 import express from 'express';
 import http from 'http';
 import cors from 'cors';

docs/source/api/plugin/drain-http-server.mdx

@@ -31,8 +31,8 @@ This plugin is exported from the `@apollo/server` package. Here's a basic exampl
 
 ```ts title="index.ts"
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import { expressMiddleware } from '@as-integrations/express5';
 import express from 'express';
 import http from 'http';
 import cors from 'cors';

docs/source/api/standalone.mdx

@@ -124,7 +124,7 @@ The `startStandaloneServer` function is not right for every use case, particular
 
 In these cases, we recommend you swap out `startStandaloneServer` for `expressMiddleware` (unless you are confident that you want to use a different Node.js framework). This change requires only a few lines and has a minimal effect on your server's existing behavior (`startStandaloneServer` uses `expressMiddleware` under the hood).
 
-> We recommend Express because it's the most popular Node.js web framework, and it integrates well with many _other_ popular libraries. It does have its limitations (for example, Express async support is not built around `Promise`s and `async` functions), but backward incompatible changes to the framework are rarer than in newer libraries.
+> We recommend Express because it's the most popular Node.js web framework, and it integrates well with many _other_ popular libraries.
 
 ### Example
 
@@ -150,20 +150,22 @@ console.log(`🚀  Server ready at ${url}`);
 ```
 </MultiCodeBlock>
 
-To swap to using `expressMiddleware`, you'll first need to install the following packages so you'll be able to set up CORS for your server:
+To swap to using `expressMiddleware`, you'll first need to install the following packages: the Express library, Apollo's integration between Express and Apollo Server, and the CORS middleware for Express:
 
 ```bash
-npm install express cors
+npm install @as-integrations/express5 express cors
 ```
 
+Note that this should install v5 of Express.
+
 Next, we can modify our code to match the following:
 
 <MultiCodeBlock>
 
 ```ts
 // npm install @apollo/server express graphql cors
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
+import { expressMiddleware } from '@as-integrations/express5';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
 import express from 'express';
 import http from 'http';

docs/source/data/subscriptions.mdx

@@ -139,8 +139,8 @@ A completed example of setting up subscriptions is shown below:
 
 ```ts title="index.ts"
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import { expressMiddleware } from '@as-integrations/express5';
 import { createServer } from 'http';
 import express from 'express';
 import { makeExecutableSchema } from '@graphql-tools/schema';

docs/source/deployment/lambda.mdx

@@ -470,7 +470,7 @@ If you've [changed your setup to use `@vendia/serverless-express`](#customizing-
 
 ```ts
 const { ApolloServer } = require('@apollo/server');
-const { expressMiddleware } = require('@apollo/server/express4');
+const { expressMiddleware } = require('@as-integrations/express5');
 const serverlessExpress = require('@vendia/serverless-express');
 const express = require('express');
 const cors = require('cors');
@@ -519,7 +519,7 @@ You can update your Apollo Server setup to the following to have a fully functio
 
 ```ts
 const { ApolloServer } = require('@apollo/server');
-const { expressMiddleware } = require('@apollo/server/express4');
+const { expressMiddleware } = require('@as-integrations/express5');
 const serverlessExpress = require('@vendia/serverless-express');
 const express = require('express');
 const cors = require('cors');

docs/source/integrations/building-integrations.md

@@ -15,9 +15,9 @@ Server in their web framework of choice.
 ## Overview
 
 The primary responsibility of an Apollo Server integration is to translate
-requests and responses between a web framework's native format to the format used by `ApolloServer`. This article conceptually covers how to build an integration, using the [Express integration](https://github.com/apollographql/apollo-server/blob/main/packages/server/src/express4/index.ts) (i.e.,`expressMiddleware`) as an example.
+requests and responses between a web framework's native format to the format used by `ApolloServer`. This article conceptually covers how to build an integration, using the [Express integration](https://github.com/apollo-server-integrations/apollo-server-integration-express5/blob/main/src/index.ts) (i.e.,`expressMiddleware`) as an example.
 
-> For more examples, see these Apollo Server 4 [integrations demos for Fastify and Lambda](https://github.com/apollographql/server-v4-integration-demos/tree/main/packages).
+> For more examples, see the source of the [community-maintained Apollo Server integrations](./integration-index).
 
 If you are building a serverless integration, we **strongly recommend** prepending your function name with the word `start` (e.g., `startServerAndCreateLambdaHandler(server)`). This naming convention helps maintain Apollo Server's standard that every server uses a function or method whose name contains the word `start` (such as `startStandaloneServer(server)`.
 
@@ -118,7 +118,7 @@ Apollo Server responds to a variety of requests via both `GET` and `POST` such a
 
 Integrations _are_ responsible for parsing a request's body and using the values to construct the `HTTPGraphQLRequest` that Apollo Server expects.
 
-In Apollo Server 4's Express integration, a user sets up the `body-parser` JSON middleware, which handles parsing JSON request bodies with a `content-type` of `application/json`. Integrations can require a similar middleware (or plugin) for their ecosystem, or they can handle body parsing themselves.
+In Apollo Server 4's Express integration, you set up the `express.json()` JSON middleware, which handles parsing JSON request bodies with a `content-type` of `application/json`. Integrations can require a similar middleware (or plugin) for their ecosystem, or they can handle body parsing themselves.
 
 For example, a correctly parsed body should have a shape resembling this:
 

docs/source/integrations/integration-index.mdx

@@ -6,9 +6,13 @@ import IntegrationTable from "../shared/integration-table.mdx"
 
 > Are you looking to build a new integration? Or help maintain an existing integration? See [Building Web Framework Integrations for Apollo Server](./building-integrations) for step-by-step guidance!
 
-Apollo Server 4 includes two built-in integrations: [`startStandaloneServer`](../api/standalone) and [`expressMiddleware`](../api/express-middleware).
+Apollo Server 4's [`startStandaloneServer`](../api/standalone) function spins up a basic web server with sensible defaults.  The server is a fully functional GraphQL server supporting all of Apollo Server's GraphQL-level customizations, but it offers minimal opportunities for HTTP-level configuration.
 
-The `startStandaloneServer` function sets useful defaults to get you started quickly. Under the hood, the `startStandaloneServer` function uses Apollo Server 4's Express integration (i.e., `expressMiddleware`). The `expressMiddleware` function is Apollo Server 4's [Express](https://expressjs.com/) integration.
+If you need more control over how your GraphQL server speaks HTTP, you should instead use an _integration_. Integrations are packages which connect the Apollo Server API to your favorite web framework.
+
+Apollo maintains an [integration](../api/express-middleware) between Apollo Server and [Express](https://expressjs.com/), the most popular Node.js web framework. The integration with Express v4 is published as [`@as-integrations/express4`](https://www.npmjs.com/package/@as-integrations/express), and the integration with Express v5 is published as [`@as-integrations/express5`](https://www.npmjs.com/package/@as-integrations/express5). Both packages export the function [`expressMiddleware`](../api/express-middleware).
+
+> The Express v4 integration is also included in the main `@apollo/server` package, exported from `@apollo/server/express4`. Its behavior is identical to the `@as-integrations/express4`. Express v5 is only supported by the external package. (A future major version of Apollo Server will remove `@apollo/server/express4`.)
 
 > Have you built, or are you maintaining, an Apollo Server integration that isn't listed here? Please [submit a PR](https://github.com/apollographql/apollo-server/blob/main/docs/source/integrations/integration-index.mdx) to be added to this list!
 

docs/source/integrations/mern.mdx

@@ -133,7 +133,7 @@ import records from "./routes/record.js";
 import gql from "graphql-tag";
 import { ApolloServer } from '@apollo/server';
 import { buildSubgraphSchema } from '@apollo/subgraph';
-import { expressMiddleware } from '@apollo/server/express4';
+import { expressMiddleware } from '@as-integrations/express5';
 import resolvers from "./resolvers.js";
 import { readFileSync } from "fs";
 //highlight-end

docs/source/migration.mdx

@@ -11,7 +11,8 @@ Apollo Server 4 focuses on improving Apollo Server's extensibility and making it
 
 Apollo Server 4 provides the following features:
 * A well-defined API with a stable HTTP abstraction, enabling contributors to easily [build and maintain integrations](./integrations/building-integrations) in their preferred frameworks.
-* A new `@apollo/server` package, combining numerous [smaller packages](#packages-merged-into-apolloserver) and including the [`startStandaloneServer`](#migrate-from-apollo-server) and [`expressMiddleware`](#migrate-from-apollo-server-express) functions.
+* A new `@apollo/server` package, combining numerous [smaller packages](#packages-merged-into-apolloserver) and including the [`startStandaloneServer`](#migrate-from-apollo-server) function.
+* Apollo-maintained packages to integrate with the Express web framework via the [`expressMiddleware`](#migrate-from-apollo-server-express) function.
 * Packages that can be used as either ECMAScript or CJS modules.
 * Experimental support for [incremental delivery](./workflow/requests#incremental-delivery-experimental) when combined with a pre-release of `graphql-js`.
 
@@ -32,7 +33,6 @@ Apollo Server 4 takes a different approach to integrations by providing a stable
 The new `@apollo/server` package contains:
 
 - The `ApolloServer` class
-- An [Express 4 integration](#migrate-from-apollo-server-express) (similar to Apollo Server 3's `apollo-server-express` package)
 - A [standalone server](#migrate-from-apollo-server) (similar to Apollo Server 3's `apollo-server` package)
 - A set of [core plugins](#plugins-are-in-deep-imports) (similar to Apollo Server 3's `apollo-server-core` package)
 
@@ -53,10 +53,12 @@ graph TB;
 ```
 
 - If you're currently using the `apollo-server` package, you should use the [`startStandaloneServer`](#migrate-from-apollo-server) function.
-- If you're currently using the `apollo-server-express` package, you should use the [`expressMiddleware`](#migrate-from-apollo-server-express) function.
+- If you're currently using the `apollo-server-express` package, you should use the [`expressMiddleware`](#migrate-from-apollo-server-express) function in the `@as-integrations/express4` package.
 
 The [`@apollo/server` package](https://www.npmjs.com/package/@apollo/server) exports these functions alongside the  `ApolloServer` class.
 
+> In Apollo Server 4, `@apollo/server` also contains a copy of the same `expressMiddleware` function from `@as-integrations/express4` package. We recommend you use the separate integration package instead of the copy in `@apollo/server`, which a future major version of Apollo Server will remove.
+
 If you are using another Apollo Server 3 framework integration package (such as `apollo-server-koa` or `apollo-server-lambda`), check out our [list of integrations](./integrations/integration-index) to see if a community-maintained integration package exists for your framework of choice.
 
 If there is no Apollo Server integration for your favorite framework _yet_, help the broader community by [building a new integration](./integrations/building-integrations)! You can also [join the discussions about maintaining our existing integrations](https://github.com/apollographql/apollo-server/labels/integration-collaborators).
@@ -187,9 +189,11 @@ Similarly, if you used the `stopGracePeriodMillis` constructor option in Apollo
 
 If you used the `apollo-server-express` package in Apollo Server 3, use the `expressMiddleware` function in Apollo Server 4 (i.e., instead of using `server.applyMiddleware` or `server.getMiddleware`).
 
+> The following assumes you are using Express v4. If you would like to use Express v5 (which was not supported by Apollo Server 3), you can follow the instructions below, but use the package `@as-integrations/express5` instead of `@as-integrations/express4`.
+
 To migrate from Apollo Server 3's `apollo-server-express` package to using the `expressMiddleware` function, do the following:
 
-1. Install the `@apollo/server` and `cors` packages.
+1. Install the `@apollo/server`, `@as-integrations/express4`, and `cors` packages.
 2. Import symbols from `@apollo/server` (i.e., instead of from `apollo-server-express` and `apollo-server-core`).
 3. Add `cors` to your server setup.
 4. Remove the Apollo Server 3 `apollo-server-express` and `apollo-server-core` packages.
@@ -234,8 +238,8 @@ looks like this in Apollo Server 4:
 ```ts title="apollo-server-4.ts"
 // npm install @apollo/server express graphql cors
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import { expressMiddleware } from '@as-integrations/express4';
 import express from 'express';
 import http from 'http';
 import cors from 'cors';
@@ -1923,7 +1927,7 @@ This section lists the TypeScript-only types (i.e., interfaces, not classes) tha
 
 Apollo Server 4 changes the name of the constructor options type from `Config` to `ApolloServerOptions`.  In Apollo Server 3, some integration packages export their own versions of this type (e.g., `ApolloServerExpressConfig`). In Apollo Server 4, there is only one `ApolloServer` type with only one constructor, so these additional types are no longer necessary.
 
-Two types in `apollo-server-express` now have more explicit names exported from `@apollo/server/express4`. `GetMiddlewareOptions` is now `ExpressMiddlewareOptions` and `ExpressContext` is now `ExpressContextFunctionArgument`.
+Two types in `apollo-server-express` now have more explicit names exported from `@as-integrations/express4`. `GetMiddlewareOptions` is now `ExpressMiddlewareOptions` and `ExpressContext` is now `ExpressContextFunctionArgument`.
 
 ### Removed types
 

docs/source/security/cors.mdx

@@ -100,8 +100,8 @@ Below, we set up and customize the CORS behavior for our `expressMiddleware` fun
 
 ```ts
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import { expressMiddleware } from '@as-integrations/express5';
 import express from 'express';
 import http from 'http';
 import { typeDefs, resolvers } from './schema';

docs/source/security/terminating-ssl.mdx

@@ -16,8 +16,8 @@ Here's an example that uses HTTPS in production and HTTP in development:
 
 ```ts title="index.ts"
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
+import { expressMiddleware } from '@as-integrations/express5';
 import typeDefs from './graphql/schema';
 import resolvers from './graphql/resolvers';
 import cors from 'cors';

packages/server/README.md

@@ -90,30 +90,29 @@ Open the URL it prints in a web browser. It will show [Apollo Sandbox](https://w
 
 ## Getting started: Express middleware
 
-Apollo Server's built-in Express middleware lets you run your GraphQL server as part of an app built with [Express](https://expressjs.com/), the most popular web framework for Node.
+Apollo Server's Express middleware lets you run your GraphQL server as part of an app built with [Express](https://expressjs.com/), the most popular web framework for Node.
 
-First, install Apollo Server, the JavaScript implementation of the core GraphQL algorithms, Express, and two common Express middleware packages:
+First, install Apollo Server, its Express middleware, the JavaScript implementation of the core GraphQL algorithms, Express, and the standard Express middleware package for CORS headers:
 
 ```
-npm install @apollo/server graphql express cors body-parser
+npm install @apollo/server @as-integrations/express5 graphql express cors
 ```
 
 If using Typescript you may also need to install additional type declaration packages as development dependencies to avoid common errors when importing the above packages (i.e. Could not find a declaration file for module '`cors`'):
 
 ```
-npm install --save-dev @types/cors @types/express @types/body-parser
+npm install --save-dev @types/cors @types/express
 ```
 
 Then, write the following to `server.mjs`. (By using the `.mjs` extension, Node lets you use the `await` keyword at the top level.)
 
 ```js
 import { ApolloServer } from '@apollo/server';
-import { expressMiddleware } from '@apollo/server/express4';
+import { expressMiddleware } from '@as-integrations/express5';
 import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer'
 import express from 'express';
 import http from 'http';
 import cors from 'cors';
-import bodyParser from 'body-parser';
 
 // The GraphQL schema
 const typeDefs = `#graphql
@@ -142,7 +141,7 @@ await server.start();
 
 app.use(
   cors(),
-  bodyParser.json(),
+  express.json(),
   expressMiddleware(server),
 );