---
title: GraphQL
slug: oip-next/v4/reference/starter-kit/graphql
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-09T13:08:21.000Z
---

La couche GraphQL est gérée par [Apollo Server](https://www.apollographql.com/docs/apollo-server) et [Apollo Client](https://www.apollographql.com/docs/react). L'interface [Apollo Sandbox](https://www.apollographql.com/docs/graphos/explorer/sandbox/) est accessible par défaut via l'URL [http://localhost:5500/graphql](http://localhost:5500/graphql) ; elle permet de visualiser le schéma complet GraphQL et tester les *queries* et *mutations*.

# Enrichir la configuration par défaut

## Définir un type

***Etape 1*** : Créez un fichier pour votre nouveau type dans le dossier `server/graphql/types`.

Exemple d'un type `Business` :

:::CodeblockTabs
business-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const BusinessType = gql`
  type Business {
    message: String
  }
`;
```
:::

***Etape 2*** : Editez le fichier `server/index.mjs` pour ajouter la déclaration de votre nouveau type.

:::CodeblockTabs
index.mjs

```javascript
import { BusinessType } from 'graphql/types/business-type.mjs';

let serverConfig = {
  graphql: {
    // Add BusinessType to typeDefs
    typeDefs: R.concat(
      R.map(R.prop('typeDefs'), schemaTypes),
      [ExtendedProcessType, BusinessType]
    )
  }
};
```
:::

### Type input

Votre type doit être déclaré avec `input` et non `type`.

:::CodeblockTabs
business-input-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const BusinessInputType = gql`
  input BusinessInputType {
    message: String
  }
`;
```
:::

### Type response

Votre type doit implémenter `QueryResponse`.

:::CodeblockTabs
business-response-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const BusinessResponseType = gql`
  type BusinessResponse implements QueryResponse {
    ok: Boolean!
    error: String
    business: Business
  }
`;
```
:::

## Définir un type d'une query

### Partie serveur

***Etape 1*** : Créez un fichier pour votre nouveau type dans le dossier `server/graphql/types`.

Exemple :

:::CodeblockTabs
query-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const QueryType = gql `
  extend type Query {
    business: BusinessResponse
  }
`;
```
:::

***Etape 2*** : Créez le fichier de la fonction *resolver* de la *query* dans le dossier `server/graphql/resolvers/queries`.

:::CodeblockTabs
business-resolver.mjs

```javascript
import { OK } from '@fasstech/oip-starter-utils/server';

export const businessResolver = ({ process, sessionId }) => {
  return OK({ business: { message: 'hello world!' } });
};
```
:::

***Etape 3*** : Créez le fichier `server/graphql/resolvers/index.mjs`.

```javascript
import { businessResolver } from './queries/business-resolver.mjs';

export const resolvers = {
  Query: {
    business: (parent, args, context) => businessResolver(context)
  }
};
```

***Etape 4*** : Editez le fichier `server/index.mjs` pour ajouter la déclaration de votre nouveau type.

:::CodeblockTabs
index.mjs

```javascript
import { resolvers } from 'graphql/resolvers/index.mjs';

let serverConfig = {
  graphql: {
    resolvers: R.concat(
      R.pipe(R.map(R.prop('resolvers')), R.reject(R.anyPass([R.isNil, R.isEmpty])))(schemaTypes),
      resolvers
    )
  }
};
```
:::

### Partie client

Créez un fichier dans le dossier `app/graphql/queries`.

:::CodeblockTabs
business.js

```javascript
import { gql } from '@apollo/client';

export const BusinessQuery = gql`
  query BusinessQuery {
    business {
      business {
        message
      }
      ok
      error
    }
  }
`;
```
:::

### Hook

Pour utiliser la *query* dans une vue, créez un *hook* dans le dossier `app/hooks`.

:::CodeblockTabs
use-business.hook.js

```javascript
import { useQuery } from '@apollo/client';
import { BusinessQuery } from '../graphql/queries/business.js';

export const useBusinessQuery = (args) => {
  const { data, error, loading, refetch } = useQuery(BusinessQuery, args);

  return {
    error,
    loading,
    refetch,
    business: data?.business?.business ?? {}
  };
};
```
:::

### Utilisation dans une vue

```javascript
import { useBusinessQuery } from '../../app/hooks/use-business.hook.js';

const MyView = () => {
  const { business } = useBusinessQuery();
  
  return (
    <div>
      <pre>{JSON.stringify(business)}</pre>
    </div>
  );
};
```

## Définir un type d'une mutation

### Partie serveur

***Etape 1*** : Créez un fichier pour votre nouveau type dans le dossier `server/graphql/types`.

Exemple :

:::CodeblockTabs
mutation-type.mjs

```javascript
import { gql } from 'graphql-tag';

export const MutationType = gql`
  extend type Mutation {
    createBusiness(input: BusinessInputType!): BusinessResponse
  }
`;
```
:::

***Etape 2*** : Créez le fichier de la fonction *resolver* de la *mutation* dans le dossier `server/graphql/resolvers/mutations`.

:::CodeblockTabs
create-business-resolver.mjs

```javascript
import { OK } from '@fasstech/oip-starter-utils/server';

export const createBusinessResolver = (context, { input }) => {
  const { message } = input;
  return OK({ business: { message } });
};
```
:::

***Etape 3*** : Créez le fichier `server/graphql/resolvers/index.mjs`.

:::CodeblockTabs
index.mjs

```javascript
import { createBusinessResolver } from './mutations/create-business-resolver.mjs';

export const resolvers = {
  Mutation: {
    createBusiness: (parent, args, context) => createBusinessResolver(context, args)
  }
};

```
:::

***Etape 4*** : Editez le fichier `server/index.mjs` pour ajouter la déclaration de votre nouveau type.

:::CodeblockTabs
index.mjs

```javascript
import { resolvers } from 'graphql/resolvers/index.mjs';

let serverConfig = {
  graphql: {
    resolvers: R.concat(
      R.pipe(R.map(R.prop('resolvers')), R.reject(R.anyPass([R.isNil, R.isEmpty])))(schemaTypes),
      resolvers
    )
  }
};
```
:::

### Partie client

Créez un fichier dans le dossier `app/graphql/mutations`.

:::CodeblockTabs
create-business.js

```javascript
import { gql } from '@apollo/client';

export const CreateBusiness = gql`
  mutation CreateBusiness($input: BusinessInputType!) {
    createBusiness(input: $input) {
      business {
        message
      }
      ok
      error
    }
  }
`;
```
:::

### Hook

Pour utiliser la *mutation* dans une vue, créez un *hook* dans le dossier `app/hooks`.

:::CodeblockTabs
use-create-business.hook.js

```javascript
import { useCommitMutation } from '@@views/_common/hooks/useCommitMutation.js';
import { CreateBusiness } from '../graphql/mutations/create-business.js';

export const useCreateBusinessMutation = () => {
  return useCommitMutation(CreateBusiness, { dataProp: 'createBusiness' });
};
```
:::

### Utilisation dans une vue

:::CodeblockTabs
MyView\.jsx

```javascript
import { useCreateBusinessMutation } from '../../app/hooks/use-create-business.hook.js';

const MyView = () => {
  const { onFormSubmit: mutate } = useCreateBusinessMutation();

  const onMutate = () => {
    mutate({ message: 'is magic' }, (ok, error, data) => {
      if (!ok) {
        console.error(error);
        return;
      }
      
      console.log(data);
    });
  };
  
  return (
    <div>      
      <button onClick={onMutate}>Mutate</button>
    </div>
  );
};
```
:::
