Skip to the content

Relay

@apollion-dsi/relay packages the Relay setup an Apollion app repeats: the Environment with auth, retries, cache and subscriptions; one provider for every Relay hook; a Promise-based commitMutation; updater helpers; and @live read helpers. It is opt-in — @apollion-dsi/core has no Relay dependency, and no core component needs it.
Relay

The rule

  • Create the environment once with CreateRelayEnvironment and mount it once with EnvironmentProvider at the app root.
  • Do not also mount react-relay's RelayEnvironmentProvider: EnvironmentProvider already does.
  • Import from subpaths (@apollion-dsi/relay/commitMutation, @apollion-dsi/relay/liveState) when you need one module.
  • Leave graphqlErrorPolicy on legacy unless the screen must keep partial data.

How it works

yarn add @apollion-dsi/relay react-relay relay-runtime
yarn add --dev relay-compiler

React is a peer dependency. Configure relay-compiler in your app to generate the __generated__ artifacts. The @live docblock and @client_polling stay in that app's schema. This package does not ship the compiler config.

import { CreateRelayEnvironment, EnvironmentProvider } from '@apollion-dsi/relay';

const { Environment, StorageHandler } = new CreateRelayEnvironment({
  url: 'https://api.example.com/graphql/',
  useAuthorization: true,
  authUrl: 'https://api.example.com/auth/',
});

<EnvironmentProvider environment={Environment}>
  <App />
</EnvironmentProvider>;

StorageHandler stores the session tokens in bearer mode. With useAuthorization, GraphQL requests and the user/me probe send Authorization: Bearer <token>. The header stays on / unless you pass loginRoute.

graphqlErrorPolicy defaults to legacy: a GraphQL errors array probes the session and goes out through sink.error, so partial data is dropped. payload calls sink.next when the body has data. The session is probed, and storage cleared, only when an error status_code is in authenticationErrors. A transport TypeError does not clear storage.

Subscriptions use graphql-ws. In bearer mode the socket sends { Authorization: 'Bearer <token>' } on every connect, including reconnect, and the client is disposed when the last subscriber leaves. Cookie mode uses the browser cookie on the handshake. The token is not placed in the URL.

@live is a resolver docblock, not a transport. liveState notifies only when Object.is changes. batchLiveStateUpdates batches those notifications. subscriptionLiveState reads suspenseSentinel() until the first payload, then batches, and disposes the subscription when the last listener leaves. A normalized payload still needs a global id.

@client_polling(interval: Int!) is a directive on a query. The compiler writes metadata.live.polling_interval in milliseconds. This package polls that interval and forces those ticks past the response cache. If cacheConfig.poll is already set, this package does not poll again.

Module
What it does
Environment factory: auth, retries, cache, subscriptions, persisted queries
the single provider behind useEnvironment() and every react-relay hook
Promise wrapper; rejects when onCompleted gets a non-empty errors array
updater helpers for lists and connections
@live helpers: notify on change, batch, one subscription
Scrolls sideways inside the table. The page does not.

Pitfalls

  • Two providers over the same environment (EnvironmentProvider plus RelayEnvironmentProvider) → keep only EnvironmentProvider; migrating is a deletion.
  • A new CreateRelayEnvironment inside a component → create it at module level so the store survives re-renders.
  • usePersistedQueries: true without persistConfig in the Relay compiler config → the first request throws; configure the compiler first.
  • A GraphQL @live that only sets metadata.live.config_id is not a push channel in this package.
  • Passing loginRoute: '/' strips Authorization on the home page. Omitting loginRoute does not.
  • fetch-multipart-graphql reads @defer and @stream. Uploads are multipart form fields.

See also