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.

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

Conversation

vladar
Copy link
Contributor

@vladar vladar commented Dec 18, 2020

Description

Add a section to the gatsby-source-graphql plugin docs about Apollo links and how to compose them.

Related Issues

See #28680

@gatsbot gatsbot bot added the status: triage needed Issue or pull request that need to be triaged and assigned to a reviewer label Dec 18, 2020
@vladar vladar removed the status: triage needed Issue or pull request that need to be triaged and assigned to a reviewer label Dec 18, 2020
@vladar vladar added the type: documentation An issue or pull request for improving or updating Gatsby's documentation label Dec 18, 2020
Copy link
Contributor

@meganesu meganesu left a comment

Choose a reason for hiding this comment

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

Left some suggestions. Feel free to reach out with questions or other ideas!

The plugin provides `createLink` option that you can use to enhance your network stack:
add error handling, retries, timeouts, etc. Check out [this article](https://medium.com/@joanvila/productionizing-apollo-links-4cdc11d278eb)
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.

packages/gatsby-source-graphql/README.md Show resolved Hide resolved
packages/gatsby-source-graphql/README.md Outdated Show resolved Hide resolved
packages/gatsby-source-graphql/README.md Outdated Show resolved Hide resolved
packages/gatsby-source-graphql/README.md Outdated Show resolved Hide resolved
@@ -150,6 +150,49 @@ module.exports = {
}
```

## Composing Apollo Links for production network setup

The plugin provides `createLink` option that you can use to enhance your network stack:
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 👍

@meganesu meganesu added the status: awaiting author response Additional information has been requested from the author label Dec 18, 2020
@vladar vladar requested a review from meganesu December 18, 2020 19:36
Copy link
Contributor

@meganesu meganesu left a comment

Choose a reason for hiding this comment

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

Looks great! ✨👏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bot: merge on green Gatsbot will merge these PRs automatically when all tests passes type: documentation An issue or pull request for improving or updating Gatsby's documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants