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.The rule
- Create the environment once with
CreateRelayEnvironmentand mount it once withEnvironmentProviderat the app root. - Do not also mount
react-relay'sRelayEnvironmentProvider:EnvironmentProvideralready does. - Import from subpaths (
@apollion-dsi/relay/commitMutation,@apollion-dsi/relay/liveState) when you need one module. - Leave
graphqlErrorPolicyonlegacyunless the screen must keep partialdata.
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 |
Pitfalls
- Two providers over the same environment (
EnvironmentProviderplusRelayEnvironmentProvider) → keep onlyEnvironmentProvider; migrating is a deletion. - A new
CreateRelayEnvironmentinside a component → create it at module level so the store survives re-renders. usePersistedQueries: truewithoutpersistConfigin the Relay compiler config → the first request throws; configure the compiler first.- A GraphQL
@livethat only setsmetadata.live.config_idis not a push channel in this package. - Passing
loginRoute: '/'stripsAuthorizationon the home page. OmittingloginRoutedoes not. fetch-multipart-graphqlreads@deferand@stream. Uploads are multipart form fields.