Skip to content

Misc get started tweaks and more robust useLazyQuery documentation - #12833

Merged
jerelmiller merged 21 commits into
release-4.0from
jerel/get-started-doc
Aug 8, 2025
Merged

Misc get started tweaks and more robust useLazyQuery documentation#12833
jerelmiller merged 21 commits into
release-4.0from
jerel/get-started-doc

Fix typo

c47e0e2
Select commit
Loading
Failed to load commit list.
Apollo Librarian / AI Style Review succeeded Aug 7, 2025 in 1m 39s

Style Review Completed

The pull request has 17 style issues.

Duration: 528ms
PR URL: #12833
Review Comments: The AI has posted 17 inline comments with suggestions

Summary of changes:

This pull request includes several changes to improve the clarity, readability, and tone of the documentation. Revisions were made to simplify complex sentences, remove jargon, and rephrase content to be more reader-centric and direct. Contractions were introduced to maintain an approachable tone, and imperative verbs were used for instructions. Additionally, formatting for UI elements was updated to use bold text for better visibility.

⚠️ 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 notice on line 257 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L257

The original phrasing is passive. This change uses more encouraging language ('ideal'), a contraction ('doesn't'), and simplifies the final clause for better readability and a more approachable tone.

```suggestion
The [<code>useLazyQuery</code>](../api/react/useLazyQuery) hook is ideal for manually executing queries. Unlike <code>useQuery</code>, <code>useLazyQuery</code> doesn't immediately execute its associated query. Instead, it returns a function that you call to execute the query.
```

Check warning on line 282 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L282

The original sentence is long and uses jargon ('tuple'). This revision simplifies the sentence structure for clarity and removes the `dataState` property, which is not part of the returned object.

```suggestion
The <code>useLazyQuery</code> hook returns a tuple where the first item is the execution function. The second item is an object containing the query's result, with properties like <code>loading</code>, <code>error</code>, and <code>data</code>.
```

Check notice on line 286 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L286

This change reframes the sentence to be more reader-centric ('if you provide') and uses a contraction ('doesn't') to align with the approachable voice.

```suggestion
Unlike <code>useQuery</code>, if you provide options to <code>useLazyQuery</code> that change on re-renders, the hook doesn't automatically execute the query. Instead, <code>useLazyQuery</code> waits for you to call the execution function again before running the query with the updated options.
```

Check notice on line 309 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L309

This revision uses contractions ('isn't'), favors the present tense ('use' instead of 'will be used'), and simplifies the sentence structure for better flow and readability.

```suggestion
The changed options are immediately applied to the underlying <code>ObservableQuery</code> (accessible via the <code>observable</code> property), even though the query isn't executed. This means other APIs, such as <code>refetch</code>, use the updated options even before you call the execution function again.
```

Check warning on line 317 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L317

Button names and other interactive UI elements should be formatted with bold.

```suggestion
The following example gets a specific dog's photo when you click the **Get photo** button:
```

Check warning on line 339 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L339

The original sentence is repetitive and difficult to parse. This change simplifies the structure to make the requirement clearer.

```suggestion
When using TypeScript, if the query you provide to <code>useLazyQuery</code> has required variables, you must pass them in the <code>variables</code> option to the execution function. If you don't provide this options argument, or if the <code>variables</code> option is missing required variables, you'll see a TypeScript error.
```

Check notice on line 345 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L345

This phrasing is more direct and action-oriented, which is helpful for instructional content.

```suggestion
To change variables, call the execution function again with the new variables.
```

Check warning on line 347 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L347

Button names and other interactive UI elements should be formatted with bold.

```suggestion
The following example gets the selected dog's photo when you click the **Get photo** button.
```

Check notice on line 380 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L380

This revision is more reader-centric ('until you call') and avoids repeating the word 'called' for better readability.

```suggestion
The <code>variables</code> property is empty until you call the execution function for the first time. Use the <code>called</code> property from <code>useLazyQuery</code> to check if the execution function has run at least once.
```

Check notice on line 430 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L430

The original sentence ending is slightly awkward. This change splits the sentence and rephrases the second part for improved clarity and flow.

```suggestion
In cases where you don't need to keep your component in sync with query state, use <code>client.query()</code> directly. This approach avoids unnecessary re-renders for data your component doesn't use.
```

Check notice on line 479 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L479

Use contractions like 'isn't' to maintain an approachable tone.

```suggestion
Errors always cause the promise to reject. The <code>error</code> property isn't set when the promise resolves.
```

Check notice on line 485 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L485

This revision is more reader-centric ('You can access') than the imperative 'Read', which is more suitable for explanatory text.

```suggestion
The promise resolves with an object that includes the error and any partial data from the query. You can access the partial data from the <code>data</code> property and the error from the <code>error</code> property.
```

Check notice on line 499 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L499

This change simplifies the phrasing ('is instead set to' -> 'is') and uses a contraction ('isn't') for better readability.

```suggestion
<code>data</code> might be <code>undefined</code> instead of containing partial data. This typically happens when a [network error](./error-handling#network-errors) causes the query to fail, because the error isn't associated with GraphQL execution.
```

Check warning on line 519 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L519

This revision simplifies the phrasing ('in the event a...is raised' -> 'if a...occurs') and uses a direct, imperative instruction ('Check if...') instead of 'We recommend', which is more authoritative.

```suggestion
<code>data</code> might be <code>undefined</code> if a [network error](./error-handling#network-errors) occurs. Check if <code>data</code> is <code>undefined</code> before using it to prevent issues if an error occurs during query execution.
```

Check notice on line 525 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L525

The original phrasing is slightly weak ('might find this undesirable'). This revision is more direct and clearly states the default behavior and the possibility of changing it.

```suggestion
By default, in-flight queries from <code>useLazyQuery</code> are aborted when their component unmounts, which rejects the promise. If you need the query to run to completion, you can change this behavior.
```

Check notice on line 527 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L527

Using an imperative verb ('Call this method') is more direct and instructive for the reader.

```suggestion
The promise returned by the execution function includes a <code>.retain()</code> method. Call this method to ensure the query continues running even if the component unmounts.
```

Check notice on line 548 in docs/source/data/queries.mdx

See this annotation in the file changed.

@apollo-librarian apollo-librarian / AI Style Review

docs/source/data/queries.mdx#L548

This change makes the sentence more reader-centric ('you can shorten') and improves the logical flow by adding 'so'.

```suggestion
The <code>retain()</code> method returns the original promise, so you can shorten the previous example to a single line:
```