Make readme a bit more friendly for new users

[vladshcherbin]

Hey, 👋

I'm finally trying this package (with hooks) instead of apollo mess and have some suggestions:

The biggest one is lack of examples - using Api section to gather pieces of examples in a whole picture is pretty hard for a new user and examples section suggests visiting another repos with next.js examples which also doesn't really help in a plain koa + graphql-api-koa project.

Some examples in the docs, before Api section - not codesandbox or other repo links, just some plain md examples with basic things - set up provider, write a query, run a query, run a mutation. They would really help.

Second suggestion is to move apollo comparison to bottom maybe - it's kinda big and you have to scroll a lot to get to setup/usage sections and is not needed for people, who don't use apollo or just want to quick start with this package.

Thanks and sorry for the issues, just sharing my thoughts from a new user perspective. As an author, it's sometimes not obvious to see this because you are familiar with the package. I think this changes may help new users a lot :)

[jaydenseric]

I agree it could do with some tweaking, although I don't think it's too bad.

The readme Setup and Usage sections are right; to get started, all you need to do is:

1. Create a single GraphQL instance and use GraphQLProvider to provide it for your app. This should wrap your router/routes.
2. Use the useGraphQL React hook in your components to make queries and mutations.

I don't think many people are doing SSR without Next.js. Those that are keen to piece together a custom SSR solution can read the ssr() docs. If this is you, I'm happy to help you work though it via Twitter DM's or something :)

I placed the Apollo comparison at the top, because things like the tiny bundle size and novel cache strategy and big differentiators that should be in the introduction and I didn't want to repeat much of the same content later in the readme if the comparison was at the end.

One thing I'm keen on adding to the readme is this options guide:

https://gist.github.com/jaydenseric/4186b5b72580a1120e209bb117686b28

[vladshcherbin]

The readme Setup and Usage sections are right; to get started, all you need to do is:

1. Create a single GraphQL instance and use GraphQLProvider to provide it for your app. This should wrap your router/routes.
2. Use the useGraphQL React hook in your components to make queries and mutations.

This is exactly what I'm talking about - there are steps but no examples to quickly see what it looks like or copy paste to try it.

Check for example react-apollo, while it has a website with a nice step by step get started page, there is also a usage section in the docs, also with a step by step example. This is what really helps to get started, at least for me :)

[eurobob]

@jaydenseric You don't think it's too bad because you wrote it. It makes perfect sense to you. That doesn't make it inherently intuitive. Piecing it together from the API is a tough task, and even your two steps before omit certain knowledge. How do I connect to a specific graphql server?

[jaydenseric]

Piecing it together from the API is a tough task

Every piece of the API has a realistic code example demonstrating how it's used, and there are multiple example projects linked prominently in the readme, which in my opinion cut very quickly to the chase.

Piecing it together from the API is a tough task, and even your two steps before omit certain knowledge. How do I connect to a specific graphql server?

I suspect you might have some preconceived notions about what an API for a GraphQL client should look like, perhaps from getting used to Apollo Client. A graphql-react client is pretty much zero config; you don't set the GraphQL endpoint at that level. That's why you don't see such documentation there.

If you read the useGraphQL documentation I linked, you would see that the fetch options are configured for queries/mutations independently at the component level, with a copy-pastable example using the GraphQL Pokemon API.

The API might be unfamiliar coming from Apollo or Relay Modern, but I can assure you the API surface area is much smaller, and you can do powerful things other clients can't do, like query multiple GraphQL APIs in your components.

[jaydenseric]

I've added to the useGraphQL examples an options guide for common situations:

[eurobob]

The API might be unfamiliar coming from Apollo or Relay Modern, but I can assure you the API surface area is much smaller, and you can do powerful things other clients can't do, like query multiple GraphQL APIs in your components.

This makes more sense to me now after using it, and I really appreciate your efforts to create such a minimal graphql library.

But overall the documentation is still a bit overwhelming. The examples linked aren't very self-explanatory, and it's not fully clear to me how the methods and options work together, or how to use the graphql class on it's own.

Right now I'm wanting to fetch data within a class-based component instead of a functional one, so I can't use the useGraphQL hook, but I'm a bit lost as to how to do it otherwise. This is the kind of entry-level explanation that is missing from the readme

[MWalid]

I'm new comer here, still trying to figure out how to use this. Would love to see something like a full stack example with vanilla react & koa. Some getting started copy-paste examples would do the job as well.

Coming from Apollo, this is really zero-config library, never thought it would be such an easy to get up & running. I believe if there is a getting started section on the top of the page with the following 2 pieces of code, that would save huge time for the new comers who try to figure out how this works.

Getting started

In app.js

import React from 'react'
import MyPokemon from './my-pokemon'
import { GraphQL, GraphQLProvider } from 'graphql-react'

const graphql = new GraphQL()

export default () => (
    <GraphQLProvider graphql={graphql}>
        <MyPokemon />
    </GraphQLProvider>
)

In my-pokemon.js

import React from 'react'
import { useGraphQL } from 'graphql-react'

export default ({ name = 'pikachu' }) => {
    const { loading, cacheValue = {} } = useGraphQL({
        fetchOptionsOverride(options) {
            options.url = 'https://graphql-pokemon.now.sh'
        },
        operation: {
            query: `{ pokemon(name: "${name}") { image } }`
        }
    })

    return cacheValue.data ? (
        <img src={cacheValue.data.pokemon.image} alt={name} />
    ) : loading ? (
        'Loading…'
    ) : (
        'Error!'
    )
}