Skip to content

Merge branch 'version-4' into version-5

034fca0
Select commit
Loading
Failed to load commit list.
Merged

Version 5 #7515

Merge branch 'version-4' into version-5
034fca0
Select commit
Loading
Failed to load commit list.
Apollo Librarian / AI Style Review succeeded Jul 1, 2025 in 3m 23s

Style Review Completed

The pull request has 38 style issues.

Duration: 1420ms
PR URL: #7515
Review Comments: The AI has posted 38 inline comments with suggestions

Summary of changes:

The documentation was updated to improve clarity, tone, and readability. Changes include: using imperative mood for instructions, favoring present tense, and using "might" instead of "may". Emphasis is now conveyed through italics for strong negative emphasis, rather than bold. Vague language like "here" and directional terms like "below" were replaced with more descriptive phrasing and link text. Contractions are used for a more approachable tone. The word "several" was replaced with "multiple" or "a few". "Because" is used instead of "since" or "as" for explaining reasons. "Enable" is used instead of "allow" for functionality. The tone is consistently helpful and positive, avoiding scolding language. The use of "we" was minimized, framing content relative to the reader ("you"). "Although" is preferred over "while" for contrasting phrases, and the verb form "set up" is used instead of the noun "setup".

⚠️ This review and suggested changes are AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

Annotations

Check warning on line 511 in docs/source/api/apollo-server.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/apollo-server.mdx#L511

Use the imperative mood for instructions and avoid using bold for emphasis.

```suggestion
If you use Apollo Server v4, set this option to <code>true</code> (or better yet, upgrade to v5). It mitigates a regression introduced in Apollo Server v4 where the server returns a 200 status code (instead of 400) when a client query provides invalid variables.
```

Check notice on line 654 in docs/source/api/apollo-server.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/apollo-server.mdx#L654

Favor the present tense ("yields" instead of "will yield") and use "might" instead of "may" for potential occurrences.

```suggestion
Apollo Server 4 and 5 support incremental delivery directives such as <code>@defer</code> and <code>@stream</code> when combined with pre-release version <code>17.0.0-alpha.2</code> of <code>graphql-js</code>, and so the structure of <code>response.body</code> can represent either a single result or multiple results. <code>response.body.kind</code> is either <code>'single'</code> or <code>'incremental'</code>. If it is <code>'single'</code>, then incremental delivery has not been used, and <code>response.body.singleResult</code> is an object with <code>data</code>, <code>errors</code>, and <code>extensions</code> fields. If it is <code>'incremental'</code>, then <code>response.body.initialResult</code> is the initial result of the operation, and <code>response.body.subsequentResults</code> is an async iterator that yields subsequent results. (The precise structure of <code>initialResult</code> and <code>subsequentResults</code> is defined by <code>graphql-js</code> and might change between the current pre-release of <code>graphql-js</code> v17 and its final release; if you write code that processes these values before <code>graphql-js</code> v17 has been released you might need to adapt it when the API is finalized. Apollo Server currently only supports <code>17.0.0-alpha.2</code>, not newer alphas which use a different format.)
```

Check notice on line 8 in docs/source/api/plugin/inline-trace.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/plugin/inline-trace.mdx#L8

Avoid using bold for emphasis.

```suggestion
> 📣 New since Apollo Server 4: error details are not included in traces by default. For more details, see [Error Handling](../../data/errors/#masking-and-logging-errors).
```

Check notice on line 639 in docs/source/api/plugin/landing-pages.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/plugin/landing-pages.mdx#L639

Use "because" instead of "since" when explaining a reason, and use contractions for a more approachable tone.

```suggestion
By default, Apollo Server 2 provided a GraphQL Playground landing page. For migration purposes, we've published the [<code>@apollo/server-plugin-landing-page-graphql-playground</code>](https://www.npmjs.com/package/@apollo/server-plugin-landing-page-graphql-playground) package, a GraphQL Playground plugin compatible with Apollo Server. However, we aren't supporting this plugin with documentation or security updates because the GraphQL Playground project is officially [retired](https://github.com/graphql/graphql-playground/issues/1143) and we don't recommend its continued use. Instead, we recommend migrating to the actively maintained [Apollo Sandbox](/graphos/explorer/sandbox) (the default landing page in Apollo Server) at your earliest convenience.
```

Check notice on line 18 in docs/source/api/plugin/usage-reporting.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/plugin/usage-reporting.mdx#L18

Avoid using bold for emphasis.

```suggestion
> 📣 New since Apollo Server 4: error details are not included in traces by default. For more details, see [Error Handling](../../data/errors/#masking-and-logging-errors).
```

Check notice on line 66 in docs/source/api/standalone.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/standalone.mdx#L66

The tone should be helpful and positive, not scolding.

```suggestion
The <code>context</code> function receives <code>req</code> and <code>res</code> options which are <code>http.IncomingMessage</code> and <code>http.ServerResponse</code> types. (In Apollo Server 4, these happen to be implemented using Express's subclasses which have some extra Express-provided functionality, though this was an undocumented implementation detail. In Apollo Server 5, the standalone server is not built on Express; if you need to use Express-specific request/response functionality, [swap to <code>expressMiddleware</code>](#swapping-to-expressmiddleware).)
```

Check notice on line 84 in docs/source/api/standalone.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/api/standalone.mdx#L84

Avoid using italics for emphasis.

```suggestion
An optional <code>listen</code> configuration object. The <code>listen</code> option accepts an object with the same properties as the [<code>net.Server.listen</code> options object](https://nodejs.org/api/net.html#serverlistenoptions-callback).<br/>
```

Check notice on line 438 in docs/source/data/errors.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/errors.mdx#L438

Avoid using bold for emphasis.

```suggestion
> 📣 New in Apollo Server 4+: error details are [_not_ included in traces by default](..migration-from-v3#usage-reporting-and-inline-trace-plugins-mask-errors-by-default). Instead, <code><masked></code> replaces each error's message, and the <code>maskedBy</code> error extension replaces all other extensions. The <code>maskedBy</code> extension includes the name of the plugin that performed the masking (<code>ApolloServerPluginUsageReporting</code> or <code>ApolloServerPluginInlineTrace</code>).
```

Check notice on line 615 in docs/source/data/errors.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/errors.mdx#L615

Avoid abbreviations like "eg,". Prefer more descriptive phrasing like "such as".

```suggestion
- If Apollo Server can't parse the request into a legal GraphQL document and validate it against your schema, it responds with a 400 status code. This can also happen with other request problems, such as if a client attempts to send a batched HTTP request when <code>allowBatchedHttpRequests</code> isn't enabled, if CSRF prevention blocks a request, or if the client provided invalid variables (such as a missing required variable, or a variable of the wrong type).
```

Check notice on line 222 in docs/source/data/fetching-data.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/fetching-data.mdx#L222

Avoid using bold for emphasis.

```suggestion
Since Apollo Server 4, you can now create your data sources in the same <code>context</code> function as the rest of your per-request setup, avoiding the <code>DataSource</code> superclass entirely. We recommend [making a custom class for each data source](#creating-data-source-classes), with each class best suited for that particular source of data.
```

Check notice on line 243 in docs/source/data/fetching-data.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/fetching-data.mdx#L243

Avoid using bold for emphasis.

```suggestion
> ⚠️ Note: The community built each data source package below for use with Apollo Server 3. [As shown below](#using-datasource-subclasses), you can still use these packages in Apollo Server 4+ with a bit of extra setup.
```

Check warning on line 257 in docs/source/data/fetching-rest.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/fetching-rest.mdx#L257

Avoid using bold for emphasis and avoid vague link text like "here".

```suggestion
> 📣 New since Apollo Server 4: Apollo Server no longer automatically provides its cache to data sources. For more details, see the [data sources migration guide](../migration-from-v3/#datasources).
```

Check notice on line 414 in docs/source/data/fetching-rest.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/fetching-rest.mdx#L414

Avoid using bold for emphasis and use "instead of" as a replacement for "rather than".

```suggestion
> New since Apollo Server 4: Apollo Server now uses the [<code>@apollo/utils.fetcher</code>](../migration-from-v3#apolloutilsfetcher-replaces-apollo-server-env) interface under the hood for fetching. This interface lets you choose your own implementation of the Fetch API. To ensure compatibility with all Fetch implementations, the request provided to hooks like <code>willSendRequest</code> is a plain JS object instead of a <code>Request</code> object with methods.
```

Check notice on line 8 in docs/source/data/subscriptions.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/subscriptions.mdx#L8

Avoid using bold for emphasis.

```suggestion
Apollo Server does not provide built-in support for subscriptions in non-federated graphs.<br/><br/>
```

Check notice on line 10 in docs/source/data/subscriptions.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/subscriptions.mdx#L10

Use "enable" instead of "allow" when referring to functionality.

```suggestion
If your Apollo Server is a subgraph running behind GraphOS Router, you can use the [subscription callback plugin](../api/plugin/subscription-callback) to enable your server to respond to subscription operations.<br/><br/>
```

Check notice on line 12 in docs/source/data/subscriptions.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/subscriptions.mdx#L12

Avoid directional language like "below" and use more descriptive link text.

```suggestion
For non-federated graphs, you can [enable support for subscriptions](#enabling-subscriptions) by adding the third-party <code>graphql-ws</code> library to your server.<br/><br/>
```

Check notice on line 51 in docs/source/data/subscriptions.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/subscriptions.mdx#L51

For strong negative emphasis, use italics (e.g., _not_) instead of bold.

```suggestion
> Subscriptions are _not_ supported by Apollo Server's <code>startStandaloneServer</code> function. To enable subscriptions, you must first [swap to using the <code>expressMiddleware</code> function](../api/express-middleware) (or any other Apollo Server integration package that supports subscriptions).
```

Check notice on line 213 in docs/source/data/subscriptions.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/subscriptions.mdx#L213

Avoid using bold for emphasis.

```suggestion
> ⚠️ Running into an error? If you're using the <code>graphql-ws</code> library, your specified subscription protocol must be consistent across your backend, frontend, and every other tool you use (including [Apollo Sandbox](/graphos/explorer/subscriptions-explorer)). For more information, see [Switching from <code>subscriptions-transport-ws</code>](/apollo-server/v3/data/subscriptions/#switching-to-graphql-ws) in the Apollo Server 3 docs.
```

Check notice on line 514 in docs/source/data/subscriptions.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/subscriptions.mdx#L514

Avoid using bold for emphasis.

```suggestion
> If you plan to use subscriptions with Apollo Client, ensure [both your client and server subscription protocols are consistent](/apollo-server/v3/data/subscriptions/#switching-to-graphql-ws) for the subscription library you're using (this example uses the <code>graphql-ws</code> library).
```

Check notice on line 7 in docs/source/index.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/index.mdx#L7

Avoid using bold for emphasis.

```suggestion
> 📣 Apollo Server 5 is generally available!
```

Check warning on line 11 in docs/source/index.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/index.mdx#L11

Avoid using vague link text like "here".

```suggestion
> Still on Apollo Server 3? AS3 has been end-of-life since October 2024. We've got a [full migration guide for upgrading directly from v3 to v5](/apollo-server/migration-from-v3/). You can find the [docs for v3 in the v3 archive](/apollo-server/v3/).
```

Check notice on line 58 in docs/source/migration-from-v3.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/migration-from-v3.mdx#L58

Use "because" instead of "as" when explaining a reason.

```suggestion
> In Apollo Server 4, <code>@apollo/server</code> also contains a copy of the same <code>expressMiddleware</code> function from <code>@as-integrations/express4</code> package, exported from <code>@apollo/server/express4</code>. This copy does not exist in Apollo Server 5. Because our recommendation is to upgrade directly to Apollo Server 5 from Apollo Server 3, you should use the separate integration package.
```

Check notice on line 62 in docs/source/migration-from-v3.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/migration-from-v3.mdx#L62

Avoid using italics for emphasis.

```suggestion
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).
```

Check notice on line 68 in docs/source/migration-from-v3.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/migration-from-v3.mdx#L68

Use contractions where applicable for better readability.

```suggestion
- If you want your server to listen on a specific URL path, pass that path directly to your framework's router instead of using the [<code>path</code> option](#path-parsing). If you didn't specify a URL path, the default in Apollo Server 3 was <code>/graphql</code>, so to preserve existing behavior, you should specify that path explicitly.
```

Check notice on line 313 in docs/source/migration-from-v3.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/migration-from-v3.mdx#L313

For strong negative emphasis, use italics (e.g., _not_) instead of bold.

```suggestion
This plugin installs the [unmaintained](https://github.com/graphql/graphql-playground/issues/1143) GraphQL Playground project as a landing page and is provided for compatibility with Apollo Server 2. This package was only published once, and is _not_ actively supported. We strongly recommend you switch to the [default landing page](./api/plugin/landing-pages), which installs the actively maintained Apollo Sandbox.
```