Remplacer Relay par Apollo Client
Cette documentation a pour but de vous guider dans le remplacement de Relay par Apollo Client comme client graphQL de l'application React de votre projet.
⚠️ Avertissement
Ce guide s'applique uniquement aux projets initiés avec un OIP Starter v2.
Nous vous recommandons de suivre ce guide une fois la migration Remplacer webpack par vite.js terminée.
Si vous choisissez d’utiliser un outil de codegen avec Apollo, une étape de génération peut exister. Les avantages listés ci-dessus s’appliquent à l’approche Apollo sans codegen obligatoire, recommandée pour réduire la complexité au début de la migration.
Lien vers la documentation officielle du client Apollo : apollo-client
Apollo Client
Apollo Client est une bibliothèque moderne pour gérer les queries et mutations GraphQL côté client.
Fonctionnalités principales
- Gestion avancée du cache Définissez une politique de cache au niveau du client ou spécifiquement par requête ou mutation.
- Intégration naturelle avec React Conçu pour React et ses dernières fonctionnalités (hooks, Suspense, etc.).
Gains par rapport à un setup Relay
- API plus moderne et uniforme Initialisation du client et gestion des opérations GraphQL plus simples et plus lisibles.
- Aucune génération de fichiers obligatoire Pas d’étape supplémentaire côté client pour produire des fichiers __generated__. Résultat: suppression de milliers de lignes versionnées et d’un flux CI plus léger.
- Pas d’introspection manuelle imposée Plus besoin de lancer une étape d’introspection du schéma pour générer des artefacts avant le build des vues. Le cycle de build devient plus court et moins couplé au serveur.
- Moins de dépendances entre serveur et build front Le serveur n’a plus besoin d’être démarré en amont d’une commande de build front uniquement pour générer des fichiers GraphQL.
Pour résumer, le passage à Apollo Client nettoie le setup de votre code-base et par conséquent vous fait gagner en maintenabilité. De plus, vous gagnerez en rapidité et fluidité lors des phases de développement et du build des vues après modification de la couche graphQL.
Ce guide décrit pas à pas la procédure de migration de votre projet OIP v2 (Relay) vers Apollo Client (OIP v3). L’objectif est de remplacer progressivement Relay par Apollo, sans breaking change majeur sur vos composants ou vos handlers.
1. Préparation à l’installation
1.1 Suppression des dépendances Relay
Supprimer du package.json toutes les dépendances liées à Relay :
babel-plugin-relay
react-relay
relay-compiler
@graphql-inspector/cli
relay-runtime
vite-plugin-relay1.2 Mise à jour des dépendances GraphQL
Mettre à jour la dépendance graphql en version minimale 16.10.0 :
yarn add graphql@^16.10.01.3 Suppression des scripts Relay
Retirer du champ scripts de votre package.json :
getSchema
relay1.4 Suppression des fichiers Relay
Supprimer les fichiers obsolètes à la racine du projet :
- buildViews.sh
- relay.config.json
- schema.graphql
1.5 Nettoyage des fichiers générés
Supprimer les répertoires __generated__et nettoyer l’index Git :
find ./app -type d -name "__generated__" | xargs rm -r
find ./views -type d -name "__generated__" | xargs rm -r
git rm -r --cached app/**/__generated__ views/**/__generated__1.6 Mise à jour de OIP Tools
La version 2.4.1 de la dépendance @fasstech/oip-tools apporte le support du client Apollo pour la génération des fichiers des vues des projets v2.
Mettre à jour @fasstech/oip-tools pour le support Apollo et ajuster le script de build des vues.
yarn add @fasstech/[email protected]{
"scripts": {
"build:views": "oip-tools views build --config ./viewsConfig --extFileBackend mjs --gql-client apollo --gen-test-files false"
}
}1.7 Mise à jour de la configuration Vite
Dans vite.config.js :
- Supprimer l’import de vite-plugin-relay
- Retirer le plugin Relay de la propriété plugins
1.8 Mise à jour du Dockerfile
Supprimer toutes les références à Relay, notamment :
- La copie de relay.config.json, schema.graphql, etc.
- L’exécution de la commande yarn relay
1.9 Installation d’Apollo Client
Installer Apollo Client :
yarn add --dev @apollo/[email protected]2. Migration du dossier app
2.1 Objectif
- Remplacer le client GraphQL Relay par Apollo
- Migrer queries, mutations, hooks et providers
- Adapter Process.jsx
2.2 Migration du provider GraphQL
Fichiers à supprimer dans app/_graphql :
- Environment.js
- Query.js si non utilisé (ou l’adapter)
- populateChildren.js si non utilisé (ou l’adapter)
Fichier à créer app/_graphql/link.js :
import { ApolloLink, HttpLink, from, split } from '@apollo/client';
import { RetryLink } from '@apollo/client/link/retry';
import { onError } from '@apollo/client/link/error';
import { getMainDefinition } from '@apollo/client/utilities';
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { removeTypenameFromVariables } from '@apollo/client/link/remove-typename';
import { setContext } from '@apollo/client/link/context';
import { createClient } from 'graphql-ws';
import Tokens from '../Tokens.js';
export const createLink = (projectId) => {
const errorLink = onError(async ({ graphQLErrors, networkError }) => {
if (graphQLErrors) {
graphQLErrors.forEach(({ message, locations, path }) =>
console.log(`[GraphQL error]: Message: ${message}, Location: ${locations}, Path: ${path}`)
);
}
if (networkError) {
console.log(`[Network error]: ${networkError}`);
}
});
const retryLink = new RetryLink({
delay: {
initial: 300,
max: Infinity,
jitter: true
},
attempts: {
max: 3,
retryIf: async (error, _operation) => {
// on 401 error, try to refresh access token and retry operation
if (error.statusCode === 401) {
await Tokens.getAccessToken(true);
return true;
}
return false;
}
}
});
const authLink = setContext(async (_, { headers }) => {
const accessToken = await Tokens.getAccessToken();
return { headers: { ...headers, Authorization: `Bearer ${accessToken}` } };
});
const splitLink = split(
({ query }) => {
const definition = getMainDefinition(query);
return definition.kind === 'OperationDefinition' && definition.operation === 'subscription';
},
new GraphQLWsLink(
createClient({
url: async () => {
const response = await fetch('/graphqlwsurl');
const { url } = await response.json();
return url;
}
})
),
new HttpLink({ uri: '/graphql' })
);
return from([
new ApolloLink((operation, forward) => {
operation.setContext({ headers: { 'fasst-oav-project-id': projectId } });
return forward(operation);
}),
errorLink,
retryLink,
authLink,
removeTypenameFromVariables(),
splitLink
]);
};Voici une synthèse claire et structurée de toutes les modifications apportées au fichier app/index.jsx lors de la migration de Relay vers Apollo Client :
🧩 1. Nettoyage des imports
❌ À supprimer dans le fichier app/index.jsx
import { RelayEnvironmentProvider } from 'react-relay';
import GQLEnvironment from '@@appGraphQL/Environment';✅ À ajouter dans le fichier app/index.jsx
import { ApolloClient, ApolloProvider, InMemoryCache } from '@apollo/client';
import { createLink } from './_graphql';⚙️ 2. Suppression de l’environnement Relay
❌ À supprimer dans le fichier app/index.jsx
const environment = await GQLEnvironment();L’environnement Relay n’est plus utilisé : il est remplacé par une instance ApolloClient créée dynamiquement.
🧱 3. Suppression de la prop environment dans <App />
❌ À supprimerdans le fichier app/index.jsx
const App = ({ environment }) => { ... }
<App environment={environment} />L’environnement GraphQL est désormais injecté via le provider global ApolloProvider, plus besoin de le passer en prop.
🪄 4. Suppression du useEffect lié à Relay
❌ À supprimer dans le fichier app/index.jsx
useEffect(() => {
GQLEnvironment.projectId = data?.projectId;
}, [data?.projectId]);Le projectId est maintenant directement passé à createLink(projectId) lors de la création du client Apollo.
🧠 5. Création du client Apollo
✅ À ajouter dans le fichier app/index.jsx
const gqlClient = new ApolloClient({
cache: new InMemoryCache(),
defaultOptions: { watchQuery: { fetchPolicy: 'network-only' } },
link: createLink(data.projectId)
});L’environnement Relay n’est plus utilisé : il est remplacé par une instance ApolloClient créée dynamiquement.
🧩 6. Remplacement du provider GraphQL
❌ À supprimer dans le fichier app/index.jsx
<RelayEnvironmentProvider environment={environment}>
<App />
</RelayEnvironmentProvider>✅ À ajouter dans le fichier app/index.jsx
<ApolloProvider client={gqlClient}>
<App />
</ApolloProvider>Le provider Apollo remplace complètement le provider Relay pour exposer le client GraphQL à toute l’application.
🔄 7. Comportement général
- Le chargement du contexte client (projectId) doit précéder la création du client Apollo.
- Le provider Apollo englobe l’application entière (<App />).
- Le code est désormais plus léger (moins de boilerplate, pas d’environnement global managé manuellement).
Type de changement | Description |
|---|---|
Imports | Suppression des imports Relay / ajout des imports Apollo |
Environnement | Suppression de `GQLEnvironment` et de toute dépendance Relay |
App Component | Ne reçoit plus `environment` en prop |
Hooks | Suppression du `useEffect` Relay (`projectId`) |
Client GraphQL | Création d’un `ApolloClient` configuré avec `createLink(projectId)` |
Provider | Remplacement de `<RelayEnvironmentProvider>` par `<ApolloProvider>` |
Architecture | Passage à une logique plus standardisée et asynchrone basée sur le contexte proje |
Rappels (appliqués dans l’exemple)
- Plus aucun import Relay (RelayEnvironmentProvider, GQLEnvironment, etc.).
- Le composant <App /> ne reçoit plus de prop environment.
- Le client Apollo est créé après résolution du contexte (ici projectId) via createLink(projectId).
- _graphql/index.js ré-exporte désormais :
export * from './mutations';
export * from './queries';
export * from './link';Si vous n’avez pas useGlobalData, remplacez-le par votre mécanisme actuel (selector Redux, autre hook, ou simple fetch) pour obtenir projectId.
3. Migration des Queries GraphQL
Avant (Relay)
import { graphql } from 'react-relay';
const QProcessQuery = graphql`
query QProcessQuery {
process { ... }
}
`;
export default { query: QProcessQuery };Maintenant (Apollo)
import { gql } from '@apollo/client';
export const QProcessQuery = gql`
query QProcessQuery {
process { ... }
}
`;Points clés :
- Utiliser gql depuis @apollo/client
- Préférer un named export
- Mettre à jour app/_graphql/queries/index.js en conséquence
4. Migration des Mutations GraphQL
Avant (Relay)
import { commitMutation, graphql } from 'react-relay';Maintenant (Apollo)
import { gql } from '@apollo/client';
export const ProcessActionMutation = gql`
mutation ProcessActionMutation($viewId: ID!, $action: ID!, $object: ProcessObjectInput) {
processAction(viewId: $viewId, action: $action, object: $object) {
# ...
}
}
`;Si vous aviez une fonction d’exécution custom, remplacer commitMutation par client.mutate ou un hook useMutation.
5. Migration du fichier Process.jsx
Remplacer toutes les API Relay:
- useRelayEnvironment → useApolloClient
- fetchQuery(environment, query) → client.query({ query })
- commitMutation → client.mutate({ mutation, variables })
Exemples d’adaptation des handlers:
// Query
const client = useApolloClient();
const { data } = await client.query({ query: QProcessQuery });
// Mutation
const { data } = await client.mutate({
mutation: ProcessActionMutation,
variables: { viewId, action, object }
});Handlers concernés: onGetProcess, onAction, onNext, onGoto, onRunTask, et onBack.
6. Migration des Hooks
Synthèse de l’évolution des hooks générés dans _common/client/hooks
useFetchQuery
Le hook useFetchQuery est conçu pour gérer une query GraphQL depuis un composant de vue.
Fichier : _common/client/hooks/useFetchQuery.js
Évolution :
// before with Relay
export const useFetchQuery = ({
gqlQuery,
args,
verbose = false,
skip = false,
initialValue = {},
dataProp
}) => {
// ...
return {
isLoaded,
errorMsg,
data,
dataProp,
fetching,
isFetching,
reFetch
};
}
// now with Apollo
export const useFetchQuery = ({
gqlQuery,
args,
// verbose = false, // removed
skip = false,
initialValue = {},
dataProp
}) => {
// ...
return {
error, // added
isLoaded,
errorMsg, // different format than previously
data,
dataProp,
// fetching, // removed
isFetching,
reFetch
};
}Le hook useFetchQuery implémente désormais le hook useQuery de la librairie Apollo Client. Pour plus de détails, reportez-vous à la documentation officielle du hook useQuery d’Apollo.
Modifications :
- Paramètres : suppression de verbose
- Résultat :
- Ajout de error
- Suppression de fetching
useCommitMutation
Le hook useCommitMutation est conçu pour gérer une mutation GraphQL depuis un composant de vue.
Fichier : _common/client/hooks/useCommitMutation.js
Évolution :
// before with Relay
export const useCommitMutation = (mutation, { dataProp }) => {
// ...
return {
onFormSubmit,
isFetching
};
}
// now with Apollo
export const useCommitMutation = (mutation, { dataProp }) => {
// ...
return {
onFormSubmit,
isFetching,
called // added
};
}Le hook useCommitMutation implémente désormais le hook useMutation de la librairie Apollo Client. Pour plus de détails, consultez la documentation officielle du hook useMutation.
Modifications :
- Paramètres : aucun changement
- Résultat :
- Ajout de la propriété called (boolean), indiquant si la mutation a été appelée ou non
useSubscription
Le hook useSubscription est conçu pour gérer une subscription GraphQL depuis un composant de vue. Il remplace le hook useTaskUpdateSubscription.
Fichier : views/_common/client/hooks/useSubscription.js
Évolution : Ce hook n’est plus limité à la souscription de l’état d’une tâche. Il permet désormais de gérer toute subscription GraphQL depuis un composant de vue.
// before with Relay
export const useTaskUpdateSubscription = (variables) => {
// ...
return {
outputValue,
errorValue
};
}
// now with Apollo
export const useSubscription = (subscription, variables) => {
// ...
return {
data, // outputValue
error, // errorValue
loading // added
};
}Le hook useSubscription implémente désormais le hook useSubscription d’Apollo Client. Pour plus de détails, consultez la documentation officielle du hook useSubscription.
Modifications :
- Paramètres :
- Le premier paramètre correspond à la subscription GraphQL
- Le second paramètre correspond aux variables associées
- Résultat :
- outputValue devient data
- errorValue devient error
- Ajout de loading (boolean) indiquant si la subscription est en cours de chargement
7. Migration du dossier _common et des vues
Suite à la mise à jour de @fasstech/oip-tools, le server n'a plus besoin d'être lancé pour la génération des fichiers des vues avec Apollo comme client graphQL.
Supprimer les fichiers suivants du dossier _common (ces fichiers seront re-générés par la commande build:views) :
- views/_common/client/graphql/queries/TaskUpdateSubscription.js
- views/_common/client/hooks/useCommitMutation.js
- views/_common/client/hooks/useFetchQuery.js
- views/_common/client/hooks/useFetching.js
- views/_common/client/hooks/useTaskUpdateSubscription.js
Re-générer les vues :
yarn build:viewsLes breaking changes au niveau des composants du dossier client des vues sont limités comme suit :
- verbose est supprimé des paramètres acceptés par les hooks responsables des queries graphQL, générés dans le dossier hooks
- fetching est supprimé du résultat des hooks responsables des queries graphQL, générés dans le dossier hooks
- les appels au hook useTaskUpdateSubscription du dossier _common/client/hooks doivent être remplacés par l'utilisation du hook useSubscription
Exemple:
import { useState } from 'react';
import withProcess from '@@app/withProcess';
// before with Relay > import
import { useTaskUpdateSubscription } from '@@viewCommonHooks/useTaskUpdateSubscription';
// now with Apollo > import
import { useSubscription } from '@@viewCommonHooks/useSubscription';
import { TaskUpdateSubscription } from '@@views/_common/graphql/subscriptions/TaskUpdateSubscription';
const MyComponent = ({ context, processHandlers }) => {
// before with Relay > hook implementation
const { outputValue, errorValue } = useTaskUpdateSubscription({
taskName: 'magicTask',
projectId: context.projectId,
});
// now with Apollo > hook implementation
const { data: outputValue, error: errorValue } = useSubscription({
taskName: 'magicTask',
projectId: context.projectId,
}, TaskUpdateSubscription);
return (
<div>
...
</div>
);
};
export default withProcess(MyComponent);8. Vérification finale
Vous devez vous assurer de gérer ces breaking changes au sein des composants de vos vues. Les hooks personnalisés qui utilisent ceux générés dans le dossier _common/client/hooks sont également impactés par ces modifications et doivent être adaptés si nécessaire.
- Rechercher le terme relay dans app/ et views/
- Supprimer toute référence restante
- Lancer yarn build et yarn build:views
- Tester vos composants et handlers migrés
En cas de doute, contactez l’équipe OIP pour valider la conformité de votre migration.