GraphQL Server example

[cartogram]

Description

Adds a new example that shows how to create a custom graphQL server.

Before submitting the PR, please make sure you do the following:

• Read the Contributing Guidelines
• Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123)
• Update docs in this repository according to your change
• Run yarn changeset add if this PR cause a version bump based on Keep a Changelog and adheres to Semantic Versioning

[cartogram]

@gfscott @mcvinci I think we should have a different readme for each example. Something consistent between each example that explains a bit more about what is included. What do you think? Would you be able to help establish a template to base them on?

[gfscott]

Agree, each example should definitely include a readme, and a common template makes sense.

But to keep individual readmes from getting out of sync as the number of examples grows, I think the criteria for each readme are:

• Focus on the example's unique traits and qualities
  • Examples don't exist to familiarize you with Hydrogen in general; they exist to demonstrate one particular implementation. An example does one thing well.
• Link out to common information shared across all examples (/examples/readme.md?)
  • Let's not duplicate things like the yarn dev commands or the node version requirements, for instance. That's the kind of information that gets out of sync and can be a significant content maintenance burden over time.
  • 💡 Unless: we can automate this somehow. (Have the Shopify bot automatically commit readme updates of this common information?)

Finally: this example would be a complete, working Hydrogen storefront, correct? (even if it had no styling, etc). In that case, what separates examples from templates, if anything?

[mcvinci]

@gfscott @cartogram In terms of a template to base each example on, what do you think about the something like this:

# [Example name]

[Short description]

## Requirements

- Specify any prerequisites that need to be in place to be able to use the example in your Hydrogen app
- This might be a good section to link out to common information shared across all examples, as Graham mentioned above

## How it works

[Detailed description of how the example implementation works]

## Related resources

- [Link to related topic on Shopify.dev, if applicable]
- [Link to related area on GitHub, if applicable]

[cartogram]

In that case, what separates examples from templates, if anything?

@gfscott I was going to ask you this as well 😂 Going back to the original issue Shopify/hydrogen#817, I think a lot of it boils down to the intended use. Templates also have the CLI integration so I'm looking at this like: examples exist for reference, templates exist as a starting point.

In terms of the actual files in the folder, not much is different that I can tell.

[gfscott]

examples exist for reference, templates exist as a starting point.

This was my original position as well, but I feel less sure of the distinction as we see more real-world examples come in — many of which would be useful starting points too (The Rust/WASM example that showed up this morning, for instance.)

[cartogram]

Assume this should be hydrogen.config.js now.

[jplhomer]

Love this sort of stuff!!

[jplhomer]

Hmm, this results in the server calling itself for a request, which is generally not something we'd want to do. I didn't even think it was possible.

Could we make this a client component instead? You could even use fetchSync + Suspense.

[frandiox]

@jplhomer I read this week on Twitter that CF has finally implemented self-requests! But too early to try it I think 😅

[cartogram]

@jplhomer You know, originally I was thinking this would be a server only example, do you think would that be better? Otherwise, I can more to ClientComponent + fetchSync + Suspense 👍

[jplhomer]

We could do server-only, but in that case, there's no reason to make an HTTP call — we'd just execute the GraphQL response directly. It seems more likely that developers might want to provide a GraphQL API over HTTP to other consumers (or the client), so I think the client component makes more sense 👍

[jplhomer]

I think we should use latest for all examples, similar to Next.js - especially since these are not tied into the monorepo.