Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(gatsby-source-graphql): docs on how to use apollo links #28686

Merged
merged 8 commits into from
Dec 22, 2020
Merged

chore(gatsby-source-graphql): docs on how to use apollo links #28686

Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6428994
chore(gatsby-source-graphql): docs on how to use apollo links
vladar Dec 18, 2020
47a48dc
add comment
vladar Dec 18, 2020
7c8822a
Update packages/gatsby-source-graphql/README.md
vladar Dec 18, 2020
da4d920
Update packages/gatsby-source-graphql/README.md
vladar Dec 18, 2020
5540132
Update packages/gatsby-source-graphql/README.md
vladar Dec 18, 2020
47934f0
add suggested changes
vladar Dec 18, 2020
5af7320
rename options to pluginOptions for clarity
vladar Dec 18, 2020
d003a98
amend
vladar Dec 18, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions packages/gatsby-source-graphql/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,49 @@ module.exports = {
}
```

## Composing Apollo Links for production network setup
meganesu marked this conversation as resolved.
Show resolved Hide resolved

The plugin provides `createLink` option that you can use to enhance your network stack:
vladar marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This intro paragraph could use a bit more context, to help people figure out whether or not this option is something they need.

Possible structure: (Feel free to correct the wording, since I don't totally know how this plugin works)

(You might not actually need the headings, I just added them to highlight the different chunks of information)

Introduction

[Sentence describing the problem (e.g., "Sometimes network requests fail, but that doesn't mean you want your query to fail.")] You can use the plugin's createLink option to add an Apollo Link to your GraphQL operation.

(For more explanation of how Apollo Links work, check out this Medium article: Productionalizing Apollo Links.)

Types of Links

You can create different types of links, depending on the functionality you're trying to achieve:

  • apollo-link-retry for retrying requests that time out
  • [some other lib] for error handling
  • [some other lib] for [whatever other thing they're trying to do]

// goal of the list above is to point them toward the right lib if they're trying to do this for the first time

Parameters

To use the createLink option in your gatsby-config.js, pass it [explanation of the parameters].

Example

Here's an example of using the HTTP link with retries (using apollo-link-retry):

[code snippet]

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, this is so much better 👍

add error handling, retries, timeouts, etc. Check out [this article](https://medium.com/@joanvila/productionizing-apollo-links-4cdc11d278eb)
vladar marked this conversation as resolved.
Show resolved Hide resolved
for an excellent explanation of how it works.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add something about what the parameters are for the createLink option?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added a comment in the example. We also have some examples of this option at the beginning of the readme.

Quick example of the http link with retries (using [apollo-link-retry](https://www.npmjs.com/package/apollo-link-retry)):
vladar marked this conversation as resolved.
Show resolved Hide resolved

```js
// gatsby-config.js
const { createHttpLink } = require(`apollo-link-http`)
const { RetryLink } = require(`apollo-link-retry`)

const retryLink = new RetryLink({
delay: {
initial: 100,
max: 2000,
jitter: true,
},
attempts: {
max: 5,
retryIf: (error, operation) =>
Boolean(error) && ![500, 400].includes(error.statusCode),
},
})

module.exports = {
plugins: [
{
resolve: "gatsby-source-graphql",
options: {
typeName: "SWAPI",
fieldName: "swapi",
url: "https://api.graphcms.com/simple/v1/swapi",

createLink: options =>
ApolloLink.from([retryLink, createHttpLink(options)]),
},
},
],
}
```

## Custom transform schema function (advanced)

It's possible to modify the remote schema, via a `transformSchema` option which customizes the way the default schema is transformed before it is merged on the Gatsby schema by the stitching process.
Expand Down