Cette page a été traduite par l'API Cloud Translation.

Connexion automatique à l'espace de travail dans Chrome DevTools

L'espace de travail est une fonctionnalité puissante qui vous permet de modifier directement les fichiers sources de votre site Web depuis les outils pour les développeurs Chrome. Vous n'avez ainsi plus besoin de basculer constamment entre votre éditeur de code et le navigateur.

Présentation

Un espace de travail dans les outils pour les développeurs Chrome mappe les fichiers diffusés par un serveur Web aux fichiers d'un dossier local sur votre ordinateur. Lorsque vous activez un espace de travail pour un projet local, toutes les modifications que vous apportez aux fichiers dans le panneau Sources des outils de développement sont automatiquement enregistrées dans les fichiers de votre projet local. Cela offre une expérience d'édition fluide, comme si vous travailliez directement sur la base de code de votre projet tout en bénéficiant des insights en temps réel des outils de développement.

Avantages de la connexion automatique à un espace de travail

La connexion automatique à l'espace de travail améliore la configuration de l'espace de travail en éliminant la configuration manuelle. Au lieu d'ajouter manuellement des dossiers de projet aux Outils pour les développeurs, votre serveur de développement local peut fournir un fichier devtools.json spécial que les Outils pour les développeurs Chrome détectent automatiquement. Cela présente plusieurs avantages :

Débogage plus rapide : modifiez des fichiers dans les outils de développement et voyez les modifications instantanément sans quitter le navigateur ni enregistrer manuellement.
Modifications en temps réel : les modifications sont immédiatement répercutées dans vos fichiers locaux et dans le navigateur, ce qui accélère le développement.
Aucune configuration manuelle : automatise le mappage des fichiers de projet, ce qui réduit le temps de configuration, en particulier pour les nouveaux projets ou lors de l'intégration de membres de l'équipe.

Comment fonctionne la connexion automatique à un espace de travail ?

La connexion automatique de l'espace de travail fonctionne en exposant un fichier JSON spécifique à un chemin prédéfini sur votre serveur de développement local. Lorsque les outils pour les développeurs Chrome sont ouverts et que vous naviguez sur un site Web diffusé depuis localhost, une requête est automatiquement envoyée à :

/.well-known/appspecific/com.chrome.devtools.json

Si votre serveur répond avec un fichier devtools.json valide, les outils de développement utilisent les informations qu'il contient pour se connecter automatiquement aux dossiers sources de votre projet. Le fichier devtools.json contient généralement les éléments suivants :

{
  "workspace": {
    "root": "/Users/yourname/path/to/your/project",
    "uuid": "a-random-version-4-uuid"
  }
}

workspace.root : chemin d'accès absolu au répertoire racine de votre projet sur votre système de fichiers local.
workspace.uuid : identifiant unique (UUID v4) de votre projet. Cela permet aux outils de développement de faire la distinction entre différents projets.

Une fois que les outils pour les développeurs ont reçu et traité ce fichier, ils proposent un bouton Connect (Connecter) dans le panneau Sources > Workspaces (Espaces de travail).

Conçu pour le développement et le débogage locaux

Le mécanisme de découverte automatique de l'espace de travail via devtools.json est conçu exclusivement pour les environnements de développement locaux et ne fonctionne que lorsque votre application est diffusée à partir de localhost. Les outils de développement Chrome n'envoient la requête /.well-known/appspecific/com.chrome.devtools.json qu'en mode développement lorsque vous déboguez un projet local. Cette fonctionnalité n'est pas destinée aux environnements de production.

Autoriser l'accès aux fichiers locaux

Pour des raisons de sécurité, Chrome exige une autorisation explicite de l'utilisateur pour qu'un site Web puisse accéder aux fichiers sur votre réseau local ou votre ordinateur. Lorsque les outils pour les développeurs tentent de se connecter à votre projet local à l'aide de devtools.json, vous êtes invité à autoriser Chrome à accéder au répertoire de votre projet. Cette demande d'autorisation respecte les règles de Chrome concernant l'accès au réseau local, qui limitent les requêtes provenant de réseaux publics vers des destinations locales, sauf si l'autorisation est accordée. La possibilité de demander cette autorisation est limitée aux contextes sécurisés (HTTPS). Pour le développement local, cela signifie généralement que localhost est traité comme un contexte sécurisé.

Créer et diffuser un fichier `devtools.json`

Pour un projet frontend typique exécuté sur un serveur de développement local, vous devez configurer votre serveur pour qu'il réponde à la requête /.well-known/appspecific/com.chrome.devtools.json avec le contenu JSON approprié.

Voici comment procéder de manière générale :

Générez un UUID : vous aurez besoin d'un UUID v4. Vous pouvez en générer un à l'aide d'outils en ligne ou d'un script.
Déterminez la racine du projet : obtenez le chemin absolu du répertoire racine de votre projet.
Créez un point de terminaison : configurez votre serveur de développement pour qu'il gère les requêtes GET vers /.well-known/appspecific/com.chrome.devtools.json.
Diffuser le JSON : lorsque ce point de terminaison est atteint, diffusez une réponse JSON avec l'en-tête Content-Type: application/json et le contenu devtools.json.

Le chemin d'accès workspace.root spécifié dans votre fichier devtools.json doit être un chemin d'accès absolu au répertoire racine de votre projet sur le système de fichiers local. Cela signifie que le chemin d'accès varie en fonction de votre système d'exploitation (par exemple, /Users/yourname/projects/my-app sur macOS ou Linux, ou C:\Users\yourname\projects\my-app sur Windows) et de la configuration spécifique de votre projet. Envisagez de l'ajouter à vos fichiers ignorés (par exemple, à la liste .gitignore) pour éviter d'archiver ce fichier pour l'environnement de production.

Il est important que votre serveur génère ou diffuse ce chemin de manière dynamique, ou que vous le configuriez correctement pour votre environnement de développement. Envisagez de l'ajouter à vos fichiers ignorés (par exemple, à la liste .gitignore) pour éviter d'archiver ce fichier pour l'environnement de production.

Exemples

Il existe de nombreuses façons de fournir le fichier devtools.json, en fonction de la pile technologique de votre projet.

Node.js et Express

Ce script exécute un serveur Express minimal. Il fournit un fichier JSON à /.well-known/appspecific/com.chrome.devtools.json qui contient le chemin d'accès à projectRoot.. Il pointe vers le dossier à partir duquel le serveur est exécuté. Ajustez la variable projectRoot pour qu'elle pointe correctement vers le répertoire racine réel de votre projet, et pas nécessairement vers l'emplacement de votre script de serveur.

const express = require('express');
const path = require('path');
const { v4: uuidv4 } = require('uuid');

const app = express();
const port = 3000;

if (process.env.NODE_ENV !== 'production') {
  app.get('/.well-known/appspecific/com.chrome.devtools.json', (req, res) => {
    const projectRoot = path.resolve(__dirname);
    const workspaceUuid = uuidv4();

    res.json({
      workspace: {
        root: projectRoot,
        uuid: workspaceUuid,
      },
    });
  });
}

app.listen(port, () => {
  console.log(`Development server listening at http://localhost:${port}`);
});

Utiliser le script `devtools-json-generator`

Vous pouvez utiliser generate-devtools-json pour générer le devtools.json.

Pour générer le fichier devtools.json dans le répertoire actuel, exécutez la commande suivante :

npx generate-devtools-json

Vous pouvez également générer le fichier dans un répertoire spécifique en transmettant le répertoire en tant qu'argument :

npx generate-devtools-json /path/to/your/project

Pour en savoir plus sur devtools-json-generator, consultez la page d'accueil du projet.

Intégrations

Certains frameworks frontend et outils de compilation proposent des plug-ins ou des configurations pour simplifier ce processus.

Vite

Pour les projets basés sur Vite (y compris SvelteKit), vite-plugin-devtools-json est une solution. Il automatise la génération et la diffusion du fichier devtools.json à la volée dans.

Pour l'utiliser, installez le plug-in :

npm install -D vite-plugin-devtools-json

Ajoutez-le ensuite à votre vite.config.js (ou vite.config.ts) :

// vite.config.js
import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      // Optional: specify a custom root path if different from Vite's root
      // root: '/path/to/your/project/root',
    }),
  ],
});

Angular

Si vous utilisez ng serve pour exécuter votre projet Angular en local (et que votre version de @angular/cli est au moins 19.0.0), l'interface de ligne de commande Angular fournit un middleware qui sert automatiquement le fichier devtools.json approprié.

Par exemple, pour créer et exécuter une application :

npm install -g @angular/cli
ng new my-first-angular-app
ng serve

Lorsque vous accédez à https://localhost:4200/.well-known/appspecific/com.chrome.devtools.json, vous pouvez voir le fichier JSON généré.

Dépannage

Vous pouvez résoudre les problèmes courants liés à la connexion automatique à un espace de travail en suivant les conseils de cette section.

Supprimer un dossier des espaces de travail

Si un dossier de projet a déjà été connecté automatiquement, vous pouvez le supprimer manuellement des paramètres de votre espace de travail Outils de développement :

Accédez aux Outils pour les développeurs Chrome.
Accédez à l'onglet Sources.
Dans le panneau de gauche, sélectionnez le sous-onglet Espaces de travail.
Effectuez un clic droit sur le dossier de projet indésirable, puis sélectionnez Supprimer de l'espace de travail.

Ignorer les erreurs 404 sur le serveur

Si vous ne souhaitez pas utiliser cette fonctionnalité pour un projet spécifique et que des erreurs 404 s'affichent pour la requête /.well-known/appspecific/com.chrome.devtools.json dans les journaux de votre serveur, vous pouvez les ignorer. La requête est inoffensive si le fichier n'est pas diffusé. Vous pouvez également configurer votre serveur pour qu'il réponde avec un état 404 pour ce chemin d'accès spécifique, sans enregistrer d'erreur.

Désactiver cette fonctionnalité dans Chrome DevTools

Si vous devez désactiver la fonctionnalité de découverte automatique de l'espace de travail dans les outils pour les développeurs Chrome, vous devez définir le flag Chrome approprié :

Ouvrez Chrome et accédez à chrome://flags.
Recherchez Paramètres du projet Outils de développement et définissez-le sur Désactivé.
Vous trouverez peut-être également un indicateur associé appelé Dossiers d'espace de travail automatiques des outils de développement. Vous pouvez également le désactiver.
Relancez Chrome pour que les modifications prennent effet.

Résumé

En comprenant et en utilisant le mécanisme devtools.json, vous pouvez améliorer considérablement votre workflow de développement local avec les outils pour les développeurs Chrome.