Connessione automatica di Workspace in Chrome DevTools

Workspace è una funzionalità potente che ti consente di modificare direttamente i file sorgente del tuo sito web da Chrome DevTools, eliminando la necessità di passare continuamente dall'editor di codice al browser e viceversa.

Panoramica

Uno spazio di lavoro in Chrome DevTools mappa i file pubblicati da un server web ai file in una cartella locale sul tuo computer. Quando abiliti uno spazio di lavoro per un progetto locale, tutte le modifiche apportate ai file nel riquadro Origini di DevTools vengono salvate automaticamente nei file del progetto locale. In questo modo, l'esperienza di modifica è fluida e sembra di lavorare direttamente sul codebase del progetto, usufruendo al contempo degli approfondimenti in tempo reale di DevTools.

Vantaggi della connessione automatica del workspace

La connessione automatica del workspace migliora la configurazione del workspace eliminando la configurazione manuale. Anziché aggiungere manualmente le cartelle del progetto a DevTools, il server di sviluppo locale può fornire un file devtools.json speciale che Chrome DevTools rileva automaticamente. Questo approccio offre diversi vantaggi:

  • Debug più rapido:modifica i file in DevTools e visualizza gli aggiornamenti istantaneamente senza uscire dal browser o salvare manualmente.
  • Modifiche in tempo reale:le modifiche vengono immediatamente applicate ai file locali e al browser, migliorando la velocità di sviluppo.
  • Nessuna configurazione manuale:automatizza la mappatura dei file di progetto, riducendo i tempi di configurazione, soprattutto per i nuovi progetti o quando vengono aggiunti membri del team.

Come funziona la connessione automatica al workspace?

La connessione automatica dello spazio di lavoro funziona facendo in modo che il server di sviluppo locale esponga un file JSON specifico in un percorso predefinito. Quando Chrome DevTools è aperto e navighi in un sito web pubblicato da localhost, invia automaticamente una richiesta a:

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

Se il server risponde con un file devtools.json valido, DevTools utilizza le informazioni contenute al suo interno per connettersi automaticamente alle cartelle di origine del progetto. Il file devtools.json in genere contiene:

{
  "workspace": {
    "root": "/Users/yourname/path/to/your/project",
    "uuid": "a-random-version-4-uuid"
  }
}
  • workspace.root: il percorso assoluto della directory principale del progetto nel file system locale.
  • workspace.uuid: un identificatore univoco (UUID v4) per il tuo progetto. In questo modo, gli strumenti per sviluppatori distinguono i diversi progetti.

Una volta ricevuto ed elaborato questo file, DevTools offre un pulsante Connetti nel riquadro Origini > Workspace.

Progettato per lo sviluppo e il debug locali

Il meccanismo di rilevamento automatico dello spazio di lavoro tramite devtools.json è progettato esclusivamente per gli ambienti di sviluppo locali e funziona solo quando l'applicazione viene pubblicata da localhost. Chrome DevTools invia la richiesta /.well-known/appspecific/com.chrome.devtools.json solo in modalità di sviluppo quando esegui il debug di un progetto locale. Questa funzionalità non è destinata agli ambienti di produzione.

Concedi l'autorizzazione ad accedere ai file locali

Per motivi di sicurezza, Chrome richiede l'autorizzazione esplicita dell'utente per consentire a un sito web di accedere ai file sulla rete locale o sul computer. Quando DevTools tenta di connettersi al tuo progetto locale utilizzando devtools.json, ti verrà chiesto di concedere l'autorizzazione a Chrome per accedere alla directory del progetto. Questa richiesta di autorizzazione è conforme alle norme di accesso alla rete locale di Chrome, che limitano le richieste dalle reti pubbliche alle destinazioni locali, a meno che non venga concessa l'autorizzazione. La possibilità di richiedere questa autorizzazione è limitata ai contesti sicuri (HTTPS). Per lo sviluppo locale, di solito significa che localhost viene trattato come un contesto sicuro.

Creare e pubblicare un file devtools.json

Per un tipico progetto frontend in esecuzione su un server di sviluppo locale, devi configurare il server in modo che risponda alla richiesta /.well-known/appspecific/com.chrome.devtools.json con i contenuti JSON corretti.

Ecco un approccio generale:

  1. Genera un UUID: avrai bisogno di un UUID v4. Puoi generarlo utilizzando strumenti online o uno script.
  2. Determina la radice del progetto:ottieni il percorso assoluto della directory root del progetto.
  3. Crea un endpoint:configura il server di sviluppo per gestire le richieste GET a /.well-known/appspecific/com.chrome.devtools.json.
  4. Fornisci il JSON:quando viene raggiunto questo endpoint, fornisci una risposta JSON con l'intestazione Content-Type: application/json e i contenuti devtools.json.

Il percorso workspace.root specificato nel file devtools.json deve essere un percorso assoluto alla directory root del progetto nel file system locale. Ciò significa che il percorso varierà a seconda del sistema operativo (ad esempio, /Users/yourname/projects/my-app su macOS o Linux o C:\Users\yourname\projects\my-app su Windows) e della configurazione specifica del progetto. Valuta la possibilità di aggiungerlo ai file ignorati (ad es. all'elenco .gitignore) per evitare di archiviarlo per l'ambiente di produzione.

È importante che il server generi o pubblichi questo percorso in modo dinamico oppure che lo configuri correttamente per l'ambiente di sviluppo. Valuta la possibilità di aggiungerlo ai file ignorati (ad esempio, all'elenco .gitignore) per evitare di archiviarlo per l'ambiente di produzione.

Esempi

Esistono molti modi per fornire il file devtools.json, a seconda dello stack tecnologico del tuo progetto.

Node.js ed Express

Questo script esegue un server Express minimo. Pubblica un file JSON in /.well-known/appspecific/com.chrome.devtools.json che contiene il percorso di projectRoot.. Punta alla cartella da cui viene eseguito il server. Modifica la variabile projectRoot in modo che punti correttamente alla directory root effettiva del progetto, non necessariamente a quella in cui si trova lo script del server.

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}`);
});

Utilizza lo script devtools-json-generator

Puoi utilizzare generate-devtools-json per generare devtools.json.

Per generare il file devtools.json nella directory corrente, esegui:

npx generate-devtools-json

In alternativa, per generare il file in una directory specifica, passa la directory come argomento:

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

Scopri di più su devtools-json-generator nella home page del progetto.

Integrazioni

Alcuni framework frontend e strumenti di compilazione offrono plug-in o configurazioni per semplificare questo processo.

Vite

Per i progetti basati su Vite (incluso SvelteKit), vite-plugin-devtools-json è una soluzione. Automatizza la generazione e la pubblicazione del file devtools.json al volo.

Per utilizzarlo, installa il plug-in:

npm install -D vite-plugin-devtools-json

Poi, aggiungilo al tuo vite.config.js (o 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

Se utilizzi ng serve per eseguire il tuo progetto Angular in locale (e la tua versione di @angular/cli è almeno 19.0.0), la CLI Angular fornisce un middleware che serve automaticamente il file devtools.json corretto.

Ad esempio, per creare ed eseguire una nuova applicazione:

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

Quando vai a https://localhost:4200/.well-known/appspecific/com.chrome.devtools.json, puoi vedere il file JSON generato.

Risoluzione dei problemi

Puoi risolvere i problemi tipici relativi alla connessione automatica dello spazio di lavoro seguendo i suggerimenti riportati in questa sezione.

Rimuovere una cartella da Workspace

Se una cartella del progetto è già stata connessa automaticamente, puoi rimuoverla manualmente dalle impostazioni dello spazio di lavoro DevTools:

  • Apri Chrome DevTools.
  • Vai alla scheda Fonti.
  • Nel riquadro a sinistra, seleziona la scheda secondaria Spazi di lavoro.
  • Fai clic con il tasto destro del mouse sulla cartella del progetto indesiderata e seleziona Rimuovi dallo spazio di lavoro.

Ignora gli errori 404 sul server

Se non vuoi utilizzare questa funzionalità per un determinato progetto e visualizzi errori 404 per la richiesta /.well-known/appspecific/com.chrome.devtools.json nei log del server, puoi ignorarli. La richiesta è innocua se il file non viene pubblicato. In alternativa, puoi configurare il server in modo che risponda con uno stato 404 per questo percorso specifico senza registrare un errore.

Come disattivare questa funzionalità in Chrome DevTools

Se devi disattivare la funzionalità di rilevamento automatico dello spazio di lavoro in Chrome DevTools, devi impostare il flag di Chrome appropriato:

  • Apri Chrome e vai a chrome://flags.
  • Cerca "Impostazioni progetto DevTools" e impostalo su Disattivato.
  • Potresti anche trovare un flag correlato chiamato "DevTools Automatic Workspace Folders" che puoi disattivare.
  • Riavvia Chrome per rendere effettive le modifiche.

Riepilogo

Comprendendo e utilizzando il meccanismo devtools.json, puoi migliorare notevolmente il flusso di lavoro di sviluppo locale con Chrome DevTools.