---
contentId: dfedb4f0-badf-4a05-8b62-977c61fd6d11
part: 6
title: Connecter le front-end, VitePress et le back-end, Laravel
description: Connectez un front-end VitePress à une API Laravel avec Sanctum, CORS, la protection CSRF et un client API réutilisable.
date: 2025-02-25
seriesSlug: empower-and-dynamize-our-vitepress-blog-with-a-laravel-api
---

La synchronisation des articles est en place. L'étape suivante consiste à connecter le site VitePress à l'API Laravel.

Comme les deux applications seront déployées séparément, il ne suffit pas d'envoyer une requête vers une URL. Nous devons configurer [CORS (Cross-Origin Resource Sharing)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) et la protection contre les [CSRF (Cross-Site Request Forgery)](https://en.wikipedia.org/wiki/Cross-site_request_forgery), puis faire en sorte que le navigateur envoie les identifiants dont Laravel a besoin pour l'authentification par session.

La configuration peut sembler intimidante au début, mais nous allons traiter chaque élément séparément. Laravel fournit déjà la plupart des briques nécessaires.



> [!TIP]
> Je vous recommande de lire les articles liés si vous souhaitez approfondir ces concepts. La configuration de cet article sera plus facile à comprendre.



## Installer Laravel Sanctum

L'écosystème Laravel fournit [Sanctum](https://laravel.com/docs/12.x/sanctum#spa-authentication), qui prend en charge les jetons d'API et l'authentification par cookie pour les applications monopages (SPA).

Pour commencer, installons Sanctum :

```bash [terminal]
php artisan install:api
```

Publions ensuite le fichier de configuration de CORS :

```bash [terminal]
php artisan config:publish cors
```

CORS, ou Cross-Origin Resource Sharing, est un mécanisme de sécurité du navigateur. Par défaut, les navigateurs empêchent une page d'effectuer des requêtes vers une autre origine. Cela protège les utilisateurs contre les sites malveillants qui tenteraient d'effectuer des actions en leur nom.

Notre front-end doit communiquer avec une API hébergée sur une autre origine. Nous devons donc autoriser explicitement cette origine dans la configuration de l'API.

Configurons CORS pour autoriser les requêtes provenant de notre front-end :

```php [config/cors.php]
<?php

declare(strict_types=1);

return [
    'paths' => ['api/*', 'sanctum/csrf-cookie'],

    'allowed_methods' => ['*'],

    'allowed_origins' => [
        env('APP_FRONTEND_URL'), // [!code ++]
    ],

    'allowed_origins_patterns' => [],

    'allowed_headers' => ['*'],

    'exposed_headers' => [],

    'max_age' => 0,

    'supports_credentials' => true, // [!code highlight]

];
```

Nous parlerons du déploiement plus tard, mais retenez que nous créons deux applications : le blog et l'API qui l'enrichit. Elles seront déployées séparément, c'est pourquoi l'API doit autoriser les requêtes provenant du blog.



> [!NOTE]
> Nous pourrions déployer les deux applications derrière le même domaine avec un reverse proxy, mais cela ajouterait une complexité dont nous n'avons pas besoin ici.



Configurons ensuite Sanctum pour autoriser les requêtes de notre front-end :

```php [config/sanctum.php]
return [
    'stateful' => explode(',', (string) env('SANCTUM_STATEFUL_DOMAINS', sprintf(
        '%s%s',
        'localhost:4173,localhost:5173', // [!code highlight]
        Sanctum::currentApplicationUrlWithPort()
    ))),

  // ...
]
```

La modification importante consiste à ajouter les origines de développement du front-end aux domaines stateful de Sanctum.

Une origine de navigateur combine le protocole, le nom d'hôte et le port. En développement, `localhost:5173` et `localhost:8000` sont des origines différentes, même si elles partagent le même nom d'hôte.

Ajoutons ensuite un middleware :

```php [bootstrap/app.php]
return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->statefulApi(); // [!code ++]
    })
     ->create();
```

Ce middleware indique à Sanctum d'authentifier les requêtes avec le cookie de session Laravel plutôt qu'avec un jeton d'API. C'est l'approche que nous utiliserons depuis le front-end.

Enfin, modifions le middleware d'authentification dans `routes/api.php`. En réalité, nous utilisons le middleware Laravel par défaut, qui garantit que les requêtes respectent la configuration de Sanctum, notamment les domaines stateful.

```php [routes/api.php]
Route::middleware('auth:sanctum')->group(function () { // [!code highlight]
    // Handle authenticated requests...
});
```

Notre back-end est maintenant prêt à accepter les requêtes du front-end.

Avant de passer au front-end, terminons quelques modifications du back-end.

1. Mettez à jour `store` dans `RegisteredViaGitHubController` afin qu'elle redirige l'utilisateur vers le front-end :

```php [app/Http/Controllers/RegisteredViaGitHubController.php]
final class RegisteredViaGitHubController extends Controller
{
    public function store(): RedirectResponse
    {
        // ...

        return redirect(Config::get('app.frontend_url'));
    }
}
```

Mettez également son test à jour :

```php [tests/Http/RegisteredViaGitHub/StoreTest.php]
// ...

test('redirects to the frontend', function () {
    fakeGitHubUser();

    $this->get(route('auth.github.callback'))
        ->assertRedirect(config('app.frontend_url')); // [!code highlight]
});

// ...
```

2. Ajoutez un seeder qui génère des commentaires d'exemple :



> [!TIP]
> Supprimez le contenu existant de la méthode `run` du seeder avant d'ajouter ce code.



```php [database/seeders/DatabaseSeeder.php]
use App\Models\Post;

final class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        Post::factory()
            ->count(10)
            ->hasComments(5)
            ->create();
    }
}
```

Cela crée 10 articles avec cinq commentaires chacun, ce qui nous donne des données pour tester le front-end.

3. Recréez la base de données et exécutez les migrations :

```bash [terminal]
rm database/database.sqlite && touch database/database.sqlite && php artisan migrate --seed
```

Nous recréons la base de données car, jusqu'à présent, les tests utilisaient une base SQLite en mémoire. La base locale contient encore la table `users` créée par le scaffold initial, et non la version adaptée à l'authentification GitHub.

4. Définissez `APP_FRONTEND_URL` dans `.env` et `.env.example` avec l'URL de développement du front-end :

```ini [.env]
APP_FRONTEND_URL=http://localhost:5173
```

Jusqu'ici, elle pointait vers `http://localhost:4173`, le serveur de prévisualisation VitePress.

## Se connecter au back-end depuis le front-end

Dans cette section, nous effectuerons les premières requêtes depuis le front-end et vérifierons que la connexion fonctionne.



> [!WARNING]
> Ce n'est pas la version finale du code. Nous l'améliorerons dans l'article suivant.



### Authentification sociale

La première fonctionnalité que nous pouvons tester est l'authentification sociale. Nous ajouterons un bouton dans l'en-tête qui pointe vers `/auth/github/redirect` sur le back-end. Comme l'URL du back-end sera différente en développement et en production, nous stockerons son URL de base dans une variable d'environnement. L'utilisateur sera ensuite redirigé vers GitHub, puis vers le front-end après avoir autorisé l'application.

Pour cette variable d'environnement, nous pouvons utiliser le préfixe `VITE_` afin de l'exposer au front-end :

```ini [src/.env]
VITE_API_URL=http://localhost:8000
```



> [!TIP]
> Vous pouvez ajouter cette variable sans risque au fichier `.env.example`.



Ajoutez maintenant le bouton à l'en-tête :

```vue [.vitepress/theme/common/components/TheHeader.vue]
<script lang="ts" setup>
// ...

const loginUrl = `${import.meta.env.VITE_API_URL}/auth/github/redirect` // [!code ++]
</script>

<template>
  <header class="border-b-4 border-black bg-white p-8">
    <!-- ... -->

    <div class="flex items-center gap-6">
      <!-- ... -->

      <Button :href="loginUrl" label="Connexion" /> <!-- [!code ++] -->
    </div>
  </header>
</template>
```

Nous utilisons `VITE_API_URL` pour construire l'URL de connexion. Lorsque Vite démarre, il charge `src/.env` et expose les variables préfixées par `VITE_` via `import.meta.env`.

Nous pouvons également ajouter les types de cet objet afin d'améliorer l'expérience de développement.

1. Créez un fichier `vite-env.d.ts` à la racine du projet :

```ts [vite-env.d.ts]
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}
```

2. Installez Vite comme dépendance de développement :

```bash [terminal]
npm install -D vite
```



> [!NOTE]
> Le gestionnaire de paquets pnpm ne rend accessibles que les packages installés directement dans le projet. Même si VitePress utilise Vite, nous devons donc l'installer pour accéder à ses types.



3. Ajoutez le fichier `vite-env.d.ts` à `tsconfig.json` :

```json [tsconfig.json]
{
  "include": [
    "./.vitepress/**/*",
    "vite-env.d.ts" // [!code highlight]
  ]
}
```

`import.meta.env` est maintenant typé et TypeScript connaît `VITE_API_URL`.

<video autoplay loop muted playsinline>
  <source src="https://images.soubiran.dev/series/empower-and-dynamize-our-vitepress-blog-with-a-laravel-api/bridging-the-gap-connecting-your-frontend-and-backend/social-authentication-workflow.mp4" type="video/mp4">
</video>

En cliquant sur le bouton, nous devons être redirigés vers GitHub pour l'autorisation, puis vers le front-end. La première connexion fonctionne.

### Créer un commentaire

La deuxième fonctionnalité que nous pouvons tester est la création d'un commentaire. Si elle fonctionne, nous pourrons passer à l'article suivant en sachant que le back-end et le front-end communiquent correctement.

Pour effectuer les requêtes, nous utiliserons `ofetch`. Il encapsule l'API native `fetch` et ajoute la sérialisation des corps JSON, les tentatives automatiques, une URL de base et des intercepteurs.

```bash [terminal]
pnpm add ofetch
```

Nous effectuerons la première requête depuis `Layout.vue` comme test temporaire.

Commençons par une requête simple :

```vue [.vitepress/theme/Layout.vue]
<script lang="ts" setup>
import { ofetch } from 'ofetch'

ofetch('/api/posts/1/comments', {
  baseURL: import.meta.env.VITE_API_URL,
  method: 'POST',
  body: {
    content: 'Hello world!',
  },
  headers: {
    Accept: 'application/json',
  }
})
</script>
```

Cette requête semble suffisante, mais l'onglet réseau du navigateur montre une réponse `419`. L'aperçu de la réponse contient :

```json [Exemple]
{
  "message": "CSRF token mismatch."
  // ...
}
```

L'erreur est explicite : la requête a besoin d'un jeton CSRF.

Qu'est-ce qu'un jeton CSRF et comment le gérer dans une SPA ?

Un jeton CSRF contribue à empêcher les attaques Cross-Site Request Forgery. Il permet au serveur de vérifier qu'une requête qui modifie l'état vient bien de notre application et non d'un site malveillant agissant au nom d'un utilisateur authentifié. Dans une application rendue côté serveur, le jeton est intégré au HTML. Dans une SPA, nous devons le récupérer et l'envoyer séparément.

Laravel stocke le jeton dans la session et place également une valeur chiffrée dans un cookie que le JavaScript de notre site peut lire. Nous envoyons cette valeur dans l'en-tête `X-XSRF-TOKEN`, et Laravel la compare à celle de la session.



> [!NOTE]
> Nous ne pouvons pas faire confiance au cookie seul, car le navigateur l'envoie automatiquement avec les requêtes. C'est l'en-tête explicite qui prouve que notre JavaScript a volontairement inclus le jeton.



Ajoutons le jeton CSRF à la requête :

```vue [.vitepress/theme/Layout.vue]
<script lang="ts" setup>
import { ofetch } from 'ofetch'

function getCookie(name: string) {
  const match = document.cookie.match(new RegExp(`(^| )${name}=([^;]+)`))
  return match ? match[2] : null
}

ofetch('/api/posts/1/comments', {
  // ...
  onRequest: async ({ options }) => {
    const method = options.method?.toUpperCase() || 'GET'

    if (['GET', 'HEAD', 'OPTIONS'].includes(method)) {
      return
    }

    const xsrfToken = getCookie('XSRF-TOKEN')

    if (!xsrfToken) {
      await ofetch('/sanctum/csrf-cookie', {
        baseURL: import.meta.env.VITE_API_URL,
        credentials: 'include',
      })
    }

    options.headers.set('X-Xsrf-Token', decodeURIComponent(getCookie('XSRF-TOKEN') || ''))
  },
})
</script>
```

Cette implémentation utilise un intercepteur `ofetch` pour ajouter automatiquement le jeton CSRF. Un intercepteur est appelé à une étape précise du cycle de vie de la requête. Ici, `onRequest` modifie la requête sortante.

Nous avons besoin du jeton uniquement pour les requêtes qui modifient l'état, nous ignorons donc les méthodes sûres. L'ajouter à ces méthodes ne serait pas forcément dangereux, mais cela déclencherait un travail inutile.

Nous lisons ensuite le jeton dans le cookie. S'il n'existe pas, nous appelons l'endpoint `/sanctum/csrf-cookie` de Sanctum pour le créer.

Enfin, nous ajoutons le jeton aux en-têtes de la requête. Grâce à cette aide, le front-end peut effectuer des requêtes qui modifient l'état sans répéter la configuration CSRF à chaque fois.

Nous rendons cette aide complète dès maintenant, car nous la réutiliserons dans l'article suivant.

Actualisez la page. La requête échoue toujours avec le statut `419`. Inspectez-la :

```http [Exemple]
POST /api/posts/1/comments HTTP/1.1
Origin: http://localhost:5173
accept: application/json
x-xsrf-token: eyJpdiI6IktwK1I0UXA3K3F6Y3BvMEdKWHhGblE9PSIsInZhbHVlIjoidlgyMXlSbmlRMjhuNFNhODBLMHdUSkFJSDlQZzhObjJ2VDBIOWd1WjBrMzRZVWdqZldMZWxKcFlDMHB5ajZxZTY5bWR2amJLNTdhTFhtRHJqb3kxZlEvOFptNzdMSmZHU1FmeUw0d0pIRE1DWHRCSmZ1eFJ4aDBhN21qMW5KcDEiLCJtYWMiOiJmYjgyN2E1ZDAxMjMxZWZiZDk4MjU4MzAxOGE4OTYwOWY4ZmM1OGE3ZWMyYzM2Y2FjMTM4YWIwNGVmMDU1M2NhIiwidGFnIjoiIn0=
```

La requête contient l'en-tête `x-xsrf-token`, mais pas d'en-tête `cookie`. C'est un problème, car l'utilisateur est authentifié avec un cookie de session. Sans le cookie, le back-end ne peut ni authentifier l'utilisateur ni comparer le jeton CSRF à la session.

Pour corriger cela, ajoutez `credentials: 'include'` à la requête. Le navigateur inclura ainsi les cookies dans une requête cross-origin, exactement ce dont nous avons besoin.

```vue [.vitepress/theme/Layout.vue]
<script lang="ts" setup>
ofetch('/api/posts/1/comments', {
  // ...
  credentials: 'include', // [!code ++]
})
</script>
```

La requête fonctionne maintenant. 🎉

## Dernières réflexions

La connexion fonctionne maintenant de bout en bout. Le front-end peut appeler Laravel entre deux origines, obtenir un jeton CSRF si nécessaire et inclure le cookie de session requis pour les requêtes authentifiées.

Cette configuration nous fournit une fondation API réutilisable plutôt qu'une requête isolée. Ensuite, nous construirons une couche d'authentification partagée avec [Pinia Colada](https://pinia-colada.esm.dev/) afin que les composants puissent réagir à l'utilisateur courant et le déconnecter sans dupliquer la logique des requêtes.
