Relay: Document better how react-relay/classic should be imported

[strindhaug]

I've spent several days now wondering why I kept getting the error
RelayQL: Unexpected invocation at runtime. Either the Babel transform was not set up, or it failed to identify this call site. Make sure it is being used verbatim as Relay.QL. no matter what i did.

While looking into the source code of the babel-plugin-relay I noticed the string RelayClassic.QL several places. So I decided to try se what happened if I changed all the imports of Relay to use the name RelayClassic like so:

I changed:

import Relay from 'react-relay/classic';
//...
fragments: {
      viewer: () => Relay.QL`

to:

import RelayClassic from 'react-relay/classic';
//...
fragments: {
      viewer: () => RelayClassic.QL`

everywhere. And suddenly it started working again.

I think the documentation should state more clearly that it won't work at all unless you also change the name imported as well as where to import from.
When I read the documentation I assumed that since the code (that I inherited from a previous developer) already used import Relay from 'react-relay/classic'; that it was already fixed.

And the error message Make sure it is being used verbatim as Relay.QL. didn't make me think that I should use something else thant Relay.QL; in fact it reinforced the impression that my code was correct when it was not.

[sibelius]

can you move to relay modern?

relay classic is deprecated

[jstejada]

As @sibelius mentioned, we probably won't add documentation for using relay classic as it is deprecated. Thanks and sorry for the trouble!

[strindhaug]

But if it's deprecated (and apparently completely unusable in react-native 0.58 as far as I can tell), why isn't this fact mentioned prominently in the migration documentation?

After all it was renamed to "Relay Classic" and not "Relay Legacy" or "Relay Deprecated". The word "Classic" seems to suggest that while this is old, it's still a viable way to use it. In most other contexts "Classic" is used to refer to the "good old" original version, and is used deliberately to suggest that it's not by any means outdated just because it's old.
If that was never the intention here, then that was a pretty weird choice of word for the deprecated version... I'm sure I'm not the only one who assumed that migrating to Modern was somewhat optional because of the name "Relay Classic".

In fact I've seen a few blog posts (I don't remember what I searched for so I can't find it right now) about how to start a project using Relay Classic that suggests that the author thought it was a viable option. And a search for "is relay classic deprecated?" returns (for me at least) only two relevant results suggesting that it is, namely this issue and a blog post mentioning somewhat vaguely that "Relay Classic is being deprecated within Facebook" but that doesn't strictly mean that it's supposed to be deprecated for everyone only within Facebook.

[sibelius]

we are sorry about this,

Can you add to the docs that relay classic is completely removed after 2.0.0 release?