Conexión automática de Workspace en Chrome DevTools

Workspace es una función potente que te permite editar directamente los archivos fuente de tu sitio web desde las Herramientas para desarrolladores de Chrome, lo que elimina la necesidad de cambiar constantemente entre el editor de código y el navegador.

Descripción general

Un Workspace en Herramientas para desarrolladores de Chrome asigna los archivos que entrega un servidor web a los archivos de una carpeta local en tu computadora. Cuando habilitas un espacio de trabajo para un proyecto local, los cambios que realices en los archivos del panel Fuentes de Herramientas para desarrolladores se guardarán automáticamente en los archivos de tu proyecto local. Esto proporciona una experiencia de edición fluida, lo que hace que parezca que estás trabajando directamente en la base de código de tu proyecto mientras te beneficias de las estadísticas en tiempo real de Herramientas para desarrolladores.

Ventajas de la conexión automática del espacio de trabajo

La conexión automática del espacio de trabajo mejora la configuración, ya que elimina la necesidad de realizar ajustes manuales. En lugar de agregar manualmente carpetas de proyectos a DevTools, tu servidor de desarrollo local puede proporcionar un archivo devtools.json especial que DevTools de Chrome detecta automáticamente. Esto ofrece varios beneficios:

  • Depuración más rápida: Edita archivos en Herramientas para desarrolladores y ve las actualizaciones al instante sin salir del navegador ni guardar manualmente.
  • Cambios en tiempo real: Los cambios se reflejan de inmediato en tus archivos locales y en el navegador, lo que mejora la velocidad de desarrollo.
  • Sin configuración manual: Automatiza la asignación de archivos del proyecto, lo que reduce el tiempo de configuración, en especial para proyectos nuevos o cuando se incorporan miembros al equipo.

¿Cómo funciona la conexión automática al espacio de trabajo?

La conexión automática del espacio de trabajo funciona exponiendo un archivo JSON específico en una ruta predefinida desde tu servidor de desarrollo local. Cuando las Herramientas para desarrolladores de Chrome están abiertas y navegas por un sitio web que se publica desde localhost, se envía automáticamente una solicitud a lo siguiente:

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

Si tu servidor responde con un archivo devtools.json válido, DevTools usa la información que contiene para conectarse automáticamente a las carpetas de origen de tu proyecto. Por lo general, el archivo devtools.json contiene lo siguiente:

{
  "workspace": {
    "root": "/Users/yourname/path/to/your/project",
    "uuid": "a-random-version-4-uuid"
  }
}
  • workspace.root: Es la ruta de acceso absoluta al directorio raíz de tu proyecto en el sistema de archivos local.
  • workspace.uuid: Es un identificador único (UUID v4) para tu proyecto. Esto ayuda a DevTools a distinguir entre diferentes proyectos.

Una vez que DevTools recibe y procesa este archivo, ofrece un botón Connect en el panel Sources > Workspaces.

Diseñado para el desarrollo y la depuración locales

El mecanismo automático de detección de espacios de trabajo a través de devtools.json está diseñado exclusivamente para entornos de desarrollo locales y solo funciona cuando tu aplicación se publica desde localhost. Las Herramientas para desarrolladores de Chrome envían la solicitud /.well-known/appspecific/com.chrome.devtools.json solo en el modo de desarrollo cuando depuras un proyecto local. Esta función no está diseñada para entornos de producción.

Cómo otorgar permiso para acceder a los archivos locales

Por motivos de seguridad, Chrome requiere el permiso explícito del usuario para que un sitio web acceda a los archivos de tu red o máquina local. Cuando DevTools intente conectarse a tu proyecto local con devtools.json, se te pedirá que otorgues permiso a Chrome para acceder al directorio de tu proyecto. Esta solicitud de permiso cumple con las políticas de acceso a la red local de Chrome, que restringen las solicitudes de redes públicas a destinos locales, a menos que se otorgue permiso. La capacidad de solicitar este permiso se limita a contextos seguros (HTTPS). Para el desarrollo local, esto suele significar que localhost se trata como un contexto seguro.

Crea y publica un archivo devtools.json

Para un proyecto de frontend típico que se ejecuta en un servidor de desarrollo local, debes configurar el servidor para que responda a la solicitud /.well-known/appspecific/com.chrome.devtools.json con el contenido JSON correcto.

A continuación, te indicamos cómo puedes abordar este problema:

  1. Genera un UUID: Necesitarás un UUID v4. Puedes generar uno con herramientas en línea o una secuencia de comandos.
  2. Determina la raíz del proyecto: Obtén la ruta de acceso absoluta al directorio raíz de tu proyecto.
  3. Crea un extremo: Configura tu servidor de desarrollo para que controle las solicitudes GET a /.well-known/appspecific/com.chrome.devtools.json.
  4. Entrega el JSON: Cuando se acceda a este extremo, entrega una respuesta JSON con el encabezado Content-Type: application/json y el contenido devtools.json.

La ruta de acceso workspace.root especificada en tu archivo devtools.json debe ser una ruta de acceso absoluta al directorio raíz de tu proyecto en el sistema de archivos local. Esto significa que la ruta de acceso variará según tu sistema operativo (por ejemplo, /Users/yourname/projects/my-app en macOS o Linux, o C:\Users\yourname\projects\my-app en Windows) y la configuración específica de tu proyecto. Considera agregarlo a tus archivos ignorados (p.ej., a la lista .gitignore) para evitar registrar este archivo en el entorno de producción.

Es importante que tu servidor genere o entregue esta ruta de forma dinámica, o que la configures correctamente para tu entorno de desarrollo. Considera agregarlo a tus archivos ignorados (por ejemplo, a la lista .gitignore) para evitar confirmar este archivo para el entorno de producción.

Ejemplos

Existen muchas formas de proporcionar el archivo devtools.json, según la pila de tecnología de tu proyecto.

Node.js y Express

Esta secuencia de comandos ejecuta un servidor Express mínimo. Publica un archivo JSON en /.well-known/appspecific/com.chrome.devtools.json que contiene la ruta de acceso a projectRoot.. Apunta a la carpeta desde la que se ejecuta el servidor. Ajusta la variable projectRoot para que apunte correctamente al directorio raíz real de tu proyecto, no necesariamente donde reside la secuencia de comandos del servidor.

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

Usa la secuencia de comandos devtools-json-generator

Puedes usar generate-devtools-json para generar el devtools.json por ti.

Para generar el archivo devtools.json en el directorio actual, ejecuta el siguiente comando:

npx generate-devtools-json

O bien, para generar el archivo en un directorio específico, pasa el directorio como argumento:

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

Obtén más información sobre devtools-json-generator en la página principal del proyecto.

Integraciones

Algunos frameworks de frontend y herramientas de compilación ofrecen complementos o configuraciones para simplificar este proceso.

Vite

Para los proyectos basados en Vite (incluido SvelteKit), vite-plugin-devtools-json es una solución. Automatiza la generación y la publicación del archivo devtools.json sobre la marcha.

Para usarlo, instala el complemento:

npm install -D vite-plugin-devtools-json

Luego, agrégalo a tu 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

Si usas ng serve para ejecutar tu proyecto de Angular de forma local (y tu versión de @angular/cli es al menos 19.0.0), la CLI de Angular proporciona un middleware que entrega el archivo devtools.json correcto automáticamente.

Por ejemplo, para crear y ejecutar una aplicación nueva, haz lo siguiente:

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

Cuando navegas a https://localhost:4200/.well-known/appspecific/com.chrome.devtools.json, puedes ver el archivo JSON generado.

Solución de problemas

Puedes resolver los problemas típicos relacionados con la conexión automática del espacio de trabajo siguiendo las sugerencias de esta sección.

Cómo quitar una carpeta de los espacios de trabajo

Si una carpeta de proyecto ya se conectó automáticamente, puedes quitarla manualmente de la configuración del espacio de trabajo de Herramientas para desarrolladores:

  • Abre las Herramientas para desarrolladores de Chrome.
  • Ve a la pestaña Fuentes.
  • En el panel de la izquierda, selecciona la subpestaña Workspaces.
  • Haz clic con el botón derecho en la carpeta del proyecto que no quieras y selecciona Remove from Workspace.

Ignorar los errores 404 en el servidor

Si no quieres usar esta función para un proyecto en particular y ves errores 404 para la solicitud /.well-known/appspecific/com.chrome.devtools.json en los registros del servidor, puedes ignorar estos errores. La solicitud es inofensiva si no se entrega el archivo. Como alternativa, puedes configurar tu servidor para que responda con un estado 404 para esta ruta específica sin registrar un error.

Cómo inhabilitar esta función en las Herramientas para desarrolladores de Chrome

Si necesitas inhabilitar la función de detección automática del espacio de trabajo en las Herramientas para desarrolladores de Chrome, debes configurar la función experimental de Chrome adecuada:

  • Abre Chrome y navega a chrome://flags.
  • Busca "Configuración del proyecto de Herramientas para desarrolladores" y configúrala como Inhabilitada.
  • También es posible que encuentres una marca relacionada llamada "DevTools Automatic Workspace Folders", que también puedes inhabilitar.
  • Reinicia Chrome para que se apliquen los cambios.

Resumen

Si comprendes y utilizas el mecanismo de devtools.json, puedes mejorar significativamente tu flujo de trabajo de desarrollo local con las Herramientas para desarrolladores de Chrome.