Please provide good defaults for your project

[cpojer]

Creating issues for Relay

Reporting issues with Relay

Relay seems like a really cool project and I thought: "maybe I should use it". Unfortunately I had to spend large amounts of time trying to set it up compared to other GraphQL clients, which makes me worry that this young project will not see mass adoption in the JavaScript ecosystem despite its fantastic technical architecture.

Examples:

• I attempted to set up Relay and then starred at this error for about 30 minutes: "thread 'main' panicked at 'Expect GraphQLAsts to exist.', /Users/runner/work/relay/relay/compiler/crates/relay-compiler/src/compiler.rs:333:18". I did not know what this means, there are very few words I understand in this sentence (English is not my first language). It also pointed to a path on my file system that did not exist. I was worried that npm hacked my computer and a user named "runner" took it over. I thought, maybe it's the "src" configuration option so I removed it and changed it, and then Relay completed successfully but did not find any queries. I did not know what that meant, but I started googling how to add a query. Later, after endless browsing through your documentation, StackOverflow and later bug reports, I found somebody who posted their configuration when they ran into an unrelated issue. That configuration included the magical keyword "language": "typescript". This information is not available anywhere else on the whole Internet, I checked it all!! I was wondering, do you think it is at all possible to consider that when a source folder contains a ts or tsx file, you just like assume it is TypeScript? Sorry if this is a dumb suggestion, I am not very experienced with this but please consider changing the project to provide good defaults for the rest of us who are not lucky enough to use esoteric type-checkers like Flow.
• Related to the above, maybe your documentation texts could first introduce the concept of a query, and then introduce me to the compiler? As far as I understand Relay now, I think the query is important to be able to do the compilation but the compilation before the query is not so much.
• The step-by-step guide asks me to install babel-plugin-relay and makes use of babel-plugin-relay/macro when many people have moved on from using Babel directly. Please consider promoting vite-plugin-relay or SWC's Relay compatibility in the case of Next.js along with the existing Babel documentation. Please suggest to import graphql from react-relay or elsewhere.
• I copied so much more code to create a RelayEnvironment. I don't know exactly what this is, but it would be nice to copy less code maybe? I don't really understand the code I copied.
• I thought I was finally ready to make my query but then I got told that I have to invent my own network layer. I have again not found anything in your official scrolls and more googling was required. Then I realized this wasn't necessary. Because the documentation lacks details, the content I find elsewhere is often outdated or making things worse when I'm struggling.
• I spent three more hours trying to build a GraphQL server that Relay is happy with. Have you considered providing a "Next.js Relay GraphQL Server" or "Express Relay GraphQL Server" that people can copy and paste?
• Why does Relay still have the globally unique String id requirement? Could Relay consider generating those ids from type names and incrementing ids itself?

(PS: maybe consider changing your issue template to use HTML comments so that issues don't all start with a headline of "Creating issues for Relay")

(PSS: I love you and miss you all, but seriously maybe spend a day/week setting up a new project and making your docs useful for people other than your fellow Metamates)

[daniloab]

Hi there @cpojer

I will share some content for someone that face these points mentioned above:

configuring relay compiler

The first link inside relay home could be helpful -> https://codesandbox.io/s/relay-sandbox-nxl7i?file=/src/TodoApp.tsx

For next there is some specific content and libs about it. https://reverecre.github.io/relay-nextjs/
It is an example project running relay on front. There you can have an example of how to config the relay compiler directly into the package.json.

• relay it about helps your frontend avoid imperative data-fetching and bring the declarative data-fetching to your components. It is expected a brief knowledge about GraphQL to use it. If don't these links can be helpful:
• https://www.howtographql.com/
• Relay: the GraphQL client that wants to do the dirty work for you https://dev.to/zth/relay-the-graphql-client-that-wants-to-do-the-dirty-work-for-you-55kd
• https://relay.dev/graphql/objectidentification.htm
• https://relay.dev/docs/community-learning-resources/

@cpojer The step-by-step provides the most easier way to start a frontend with Relay. You have mentioned really cool tools to be used with Relay like vite, swc, and others. Feel free to open up new pull requests composing these new features along with the babel documentation to help the new ones from Relay to understand how to use it. (I really want to know how to use with esbuild or similar \o/)

GraphQL Servers

• https://github.com/daniloab/fullstack-playground monorepo with a GraphQL Server.
• https://github.com/daniloab/rbaf-graphql-api GraphQL Server

If does anyone having a problem with the relay and need help feel free to call me on twitter DM

[cpojer]

Thanks @daniloab. The point I'm making all of this should be part of the Relay documentation, not require me to do extensive research across the Internet only to ask more questions on GitHub.

There are four pieces that will help improve the situation:

• Improve the defaults and error messages for a new Relay setup.
• Improve the documentation to consider non-Meta use cases and setups.
• Provide a Relay client starter kit.
• Provide a tool to build a GraphQL server from scratch with Relay support, like "create-relay-graphql-server".

[josephsavona]

Hey @cpojer - thank you for the detailed and actionable feedback! We've invested a lot of effort into improving our docs, but much of our focus has been documenting using Relay after you're already set up. I appreciate the blunt feedback about the gaps in our getting started sections, it's clear we have work to do here! We are planning additional work on docs this half and will keep this section in mind. Thanks again!

[josephsavona]

Now that we've had a chance to sync up as a team and discuss, let me expand on my previous answer a bit. First, I want to reiterate that we sincerely appreciate you taking the time to engage and provide specific, actionable feedback. This is really helpful!

As I mentioned above, we are planning to work on the docs this half, and we completely agree that the getting started section needs improvement — your post reinforces this and will help us prioritize this work. The points about making TypeScript work out of the box also makes complete sense and we 100% agree we should make these changes. There are also a few other smaller changes we can make (other items that you mentioned, as well as ideas we've already considered) to reduce the amount of setup work needed for typical configurations. We have been thinking about this as improving the docs as the driver for other changes (ie, if it's complicated to document, we change the feature to be easier and then write the docs for the improved version). We likely won't get to this work until Q2, but we are absolutely planning to work on this and we'll incorporate the ideas you shared.

[damassi]

I found myself on this issue after trying out Next.js's new relay support and not being able to figure out why my relay queries aren't compiling in Relay 13. Sure enough, was missing "language": "typescript". I can only guess how many excited Next.js users wanted to try out relay only to find that queries don't even compile, only to then abandon the library assuming something is busted. +1 to detecting .tsx, and then automatically applying that setting.

However... after reading the @cpojer's full issue above, I can't help but rant a bit as an experienced user. (Please forgive).

Thank you for improving your docs from what they were, but to be honest, it still reads for a hacker computer science internal to facebook crowd. They're not friendly at all for those who don't already know relay intimately, are inconsistent, code is sloppy, still have commonjs examples everywhere (which is confusing circa 2022 -- at this point, many devs have never even seen that syntax before!) and the "getting started" / home page examples are still unnecessarily complicated / wordy! Also, many of the examples make assumptions about what the reader already knows and omit relevant import statements / variables, etc, which is always confusing for devs looking to quickly get started by copying / pasting.

In as few word as possible, it would be nice to have a getting started section that showed something as simple as this (I'm using a pre-hooks example in order to try to express utter simplicity):

import { createEnvironment, QueryRenderer } from 'react-relay' 

const environment = createEnvironment(...)

const MyComponent = () => {
  return (
    <QueryRenderer environment={environment} query={...} ... /> 
  )
}

React.render(<MyComponent />, node) 

That should be all a brand new user needs to see data rendered on the page. Then, the very next example should be showing how to use fragments / useFragment hook. And then go from there. Anything more will just overwhelm the audience.

One thing that I feel needs to be immediately fixed (since it's the entrypoint of your documentation, right on the homepage) is the docs around usePreloadedQuery. The example on home makes enough sense, but as soon as one looks at the official entry it gets confusing. A new user isn't thinking about a router for usePreloadedQuery, and would likely not understand the context in the first place. Why even bring it up, and so early in the docs? They don't even understand relay's semantics yet; how can they be thinking about where to place this thing they don't understand within the architecture of a SPA router that they likely didn't write (or even use)?

I know there might be some performance implications, but it might be much better to start the user off with useLazyLoadQuery because its conceptually simpler. Its just one hook, data gets rendered, done. For people just trying to connect to their graphql endpoint and show some data, useLazyLoadQuery is more than sufficient for their needs, and a user can instantly get up and running. It matches the ease of use of Apollo and other GraphQL client libs.

The art of good documentation writing will lead power-users to usePreloadedQuery, not start with it. When a dev needs it, they'll know. It's a matter of thinking outside of the Facebook box.

Further, how does one actually use fetchQuery? A ton of tooling is based on this formerly quasi-synchronous behavior, but docs now describe a subscription mechanism. What does a new dev do here? Do we just throw .toPromise() on the end to preserve existing tooling even though the docs suggest not to? For most users, is this caution relevant? Or just at Facebook? It's very confusing. (In my personal case with Next.js, spent so much time trying to figure out how to get the example to work only to realize that it was missing toPromise().)

But just in general, everything needs to be way simplified, and can be way simplified. As someone who has used relay every day for years and loves it very much, its deeply frustrating that the docs situation still isn't fixed, because every new teammate that we onboard walks away just straight up exhausted and wondering what it was they just got done looking at. It just doesn't need to be this way, and I don't understand how facebook can't find the budget to invest in some professional docs support for such a mission critical technology. People have been complaining about this for 5+ years! Like incessantly complaining to the point where it's almost a trade industry inside-joke. And if folks only understood just how bullet proof Relay is, how best-in-class the testing tools are, and so on and so forth, they'd come. But they get to the docs and are like... uh, nope, all of this looks crazy complicated -- when it's actually not; its the overly-complicated presentation written by folks too close to the project, because the audience they're writing for is not the everyday UI developer new to GraphQL (which it should be).

At the very least, can y'all bring someone in who isn't on the Relay core dev team to do a docs pass, and maybe a technical editor? That would very quickly help eliminate all of the assumptions that are made throughout docs.

Sorry for the long rant. It's not characteristic and I feel bad about it 😢. However, after seeing this issue I couldn't keep it in anymore because its literally what I think every single time we hire a new dev, knowing the hazing they're about to have to go through trying to learn / understand the most important (and best) library in our stack.

[damassi]

(As a side-note, props to GitHub Copilot for picking up the slack for new devs unfamiliar with the conventions and frustrated with the docs. It actually works well, but requires a large codebase that's already using Relay, and would not work for devs starting a project from scratch.)

[cpojer]

@damassi I love your recommendation of the docs slowly building up from a single file into canonical uses of Relay. This might be a bit hard to see for the people who are already experts at Relay, but I think that's the right way to go about it. Start minimal, and then build on top of it. I would also highly recommend going hooks-first and relegating the classic (or rather initial Relay Modern) API to an appendix. Right now the docs are confusing also because there are at least two ways of doing things.

[jbonta]

Thanks again for this issue! Our aim is to make Relay more usable in the coming half, and that (mostly) involves taking a hard look at Relay outside Meta, where—because of documentation, configuration, examples, or other assumptions—we've missed the mark. Some of these shortcomings are definitely on our radar and on our roadmap to address, but seeing these concrete suggestions for documentation by @damassi in one place is extremely helpful, so thank you.

[laxmikanta415]

Hey @daniloab Relay is a great tool for frontend data management. I just wanted to let you know that if you need a hand in documentation or putting examples then i would love to help. As i want everyone to know about it and easily set it up in their local so they can see the power that relay has like any other ones out there.

[daniloab]

Hey @daniloab Relay is a great tool for frontend data management. I just wanted to let you know that if you need a hand in documentation or putting examples then i would love to help. As i want everyone to know about it and easily set it up in their local so they can see the power that relay has like any other ones out there.

I believe that a good start would be to understand what are the next steps in relation to the documentation that the core team of Relay is thinking about.

At the same time, it would be a pleasure to help improve the relay docs and give you a good start.

Here is an example of a doc that I write to the back4app team. It was based on the previous doc before Relay Hooks. https://www.back4app.com/docs/react-native/graphql/get-started-relay-graphql. This doc is related to React Native environment and there are the tutorial steps and real examples on Github.

[colleen-love]

I'd like to echo this sentiment and express gratitude for everyone's responses.

I have been trying to get babel-plugin-relay working with vite 3 and it is a headache, to say the least.

[damassi]

I have been trying to get babel-plugin-relay working with vite 3 and it is a headache, to say the least.

@collinscangarella - have you been successful? What have been the issues?

[colleen-love]

The issue has mostly been due to my lack of exposure to vite and a bug in vite-plugin-relay. That being said, @tobias-tengler jumped in and fixed it almost immediately. 🏃

I'm looking forward to seeing how I can help to pay it forward. I have some good ideas about documentation, especially geared towards users who are coming from a REST API background. For us non-experts. :)

[tobias-tengler]

I've also seen lots of colleagues struggle to even setup Relay in a fresh project.

In an effort to combat this I've spent some time to create a CLI tool to automatically setup Relay in existing Vite, Next and Create React App projects: https://github.com/tobias-tengler/create-relay-app

I think this could be great for adoption, considering one just has to scaffold a project, for example with yarn create next-app, and then a single additional command is enough to fully setup Relay - no other steps required.

If you want to try it out, feel free to! It's still experimental though and CRA support has not yet been fully implemented. If you run into any issues, just let me know.

If there is interest from the maintainers to make this apart of Relay, build off of it or contribute, feel free to hmu :)

[damassi]

I'll take it for a spin and then report back 👍

[colleen-love]

@tobias-tengler Thank you for putting that together, I think that you are on spot on. Tooling solves one of the two main problems.

The other problem is a bit more nuanced. Relay requires you to build your app using paradigms that I was taught to avoid.

When I was initially selecting a graphql client I went with apollo. I considered relay but decided against it because relay wanted me to declare all of my data as props, something that years of redux training has taught me to avoid. After several months of working with graphql (and product iterations) I came to better understand graphql and realized that declaring data as props doesn't create any problems because, well, graphs. @josephsavona would you be open to me contributing to the docs in a small way?

[davidmccabe]

Thanks @cpojer and everyone who's contributed to this thread. I had a specific question (for everybody) about this suggestion:

Provide a tool to build a GraphQL server from scratch with Relay support, like "create-relay-graphql-server".

If we built this, what databases or back-end systems would be most important to support? Is there a common spec we can speak on the server that would make this useful to the most people?

Just to provide a belated update, I'm now working on Relay usability full-time, starting with new documentation but also focusing on removing obstacles like this Typescript configuration option. We've made some changes in organization that I hope will help close the feedback loop on stuff like this.

Some of you have probably seen the new beta React docs: https://beta.reactjs.org/

The new Relay docs aren't as far along but we'll be gradually opening them up over the rest of the year, with the top priority being introduction, setup, and tutorial. Like the new React docs, our new docs are written to unblock practical progress, explain relationships between features, and share the reasons for our design choices and how to make the best use of Relay.

[davidmccabe]

Closed by accident, sorry about that.

[damassi]

How exciting! I would like to just emphatically request that y'all keep the wider community in mind when writing the docs. Start with someone who doesn't need to build Facebook, but rather a simple GraphQL-backed app that contains a few pages. They don't need performance tuning, they don't need query-defined bundle splitting. They just need a query renderer and a few fragments. What is the MVP relay setup required to get started? and with the least amount of conceptual baggage? Advanced users will eagerly dig into the more advanced docs, but Relay will never get more advanced users without first onboarding those who simply want to get started building, quickly.

[davidmccabe]

@damassi Thanks, that's a great suggestion and definitely something I'm keeping in mind. The new docs aim to get you going as quickly as possible. Of course, we also want to ramp you up to all of the performance-related features that make Relay unique. But we start with a guide to the basics. They are also written exclusively for the OSS environment rather than Meta internal.

[pachkovska]

I have a project set-up with relay environment and it is perfectly working. But now I am trying to set it up with config to handle 2 relay environments and 2 graphql schemas that re provided by 2 different endpoints. And this is something I am struggling to actually find a solution for ? Is there a good example, tutorial, or a step by step guide ?
I have 2 config files, i introspected 2 schemas. I wrapped respective route components into RelayEnvironmentProvider with corresponding environment, but when I run compiler for the second schema, it throws error unknown type errors, but those types are actually known only to the first schema, so the compiler should not be looking at first schema.

If anyone has done it and can provide config advice or step by step, would greatly appreciate. This is also that could be added to the docs. I don't know if relay-compiler considers one of the schemas as default sort of speak.

[bartonyoung]

Any updates on docs?

[gabemeola]

For the googlers. In my case when using multi projects, I needed to remove the leading path prefix.

Instead of

sources: {
    './extern/site': 'main',
    './distro/network': 'second',
  },

I needed

sources: {
    'extern/site': 'main',
    'distro/network': 'second',
  },