O Workspace é um recurso avançado que permite editar diretamente os arquivos de origem do seu site no Chrome DevTools, eliminando a necessidade de alternar constantemente entre o editor de código e o navegador.
Visão geral
Um espaço de trabalho no Chrome DevTools mapeia arquivos disponibilizados por um servidor da Web para arquivos em uma pasta local no seu computador. Quando você ativa um espaço de trabalho para um projeto local, todas as mudanças feitas nos arquivos do painel Fontes das DevTools são salvas automaticamente nos arquivos do projeto local. Isso oferece uma experiência de edição integrada, fazendo com que pareça que você está trabalhando diretamente na base de código do projeto enquanto se beneficia dos insights em tempo real do DevTools.
Vantagens da conexão automática do espaço de trabalho
A conexão automática do espaço de trabalho melhora a configuração ao eliminar a configuração manual. Em vez de adicionar manualmente pastas de projetos ao DevTools, seu servidor de desenvolvimento local pode fornecer um arquivo devtools.json especial que o Chrome DevTools detecta automaticamente. Isso oferece vários benefícios:
- Depuração mais rápida:edite arquivos nas DevTools e veja as atualizações instantaneamente sem sair do navegador ou salvar manualmente.
- Mudanças em tempo real:as mudanças são refletidas imediatamente nos seus arquivos locais e no navegador, melhorando a velocidade de desenvolvimento.
- Sem configuração manual:automatiza o mapeamento de arquivos de projeto, reduzindo o tempo de configuração, especialmente para novos projetos ou ao integrar membros da equipe.
Como funciona a conexão automática do espaço de trabalho?
A conexão automática do espaço de trabalho funciona fazendo com que o servidor de desenvolvimento local exponha um arquivo JSON específico em um caminho predefinido. Quando o Chrome DevTools está aberto e você navega em um site veiculado de localhost, ele envia automaticamente uma solicitação para:
/.well-known/appspecific/com.chrome.devtools.json
Se o servidor responder com um arquivo devtools.json válido, o DevTools usará as informações dele para se conectar automaticamente às pastas de origem do projeto. O arquivo devtools.json normalmente contém:
{
"workspace": {
"root": "/Users/yourname/path/to/your/project",
"uuid": "a-random-version-4-uuid"
}
}
workspace.root: o caminho absoluto para o diretório raiz do projeto no sistema de arquivos local.workspace.uuid: um identificador exclusivo (UUID v4) para seu projeto. Isso ajuda o DevTools a distinguir entre diferentes projetos.
Depois que o DevTools recebe e processa esse arquivo, ele oferece um botão Conectar no painel Fontes > Espaços de trabalho.
Projetado para desenvolvimento e depuração locais
O mecanismo automático de descoberta de espaço de trabalho por devtools.json foi projetado exclusivamente para ambientes de desenvolvimento local e só funciona quando o aplicativo é veiculado de localhost. O Chrome DevTools envia a solicitação /.well-known/appspecific/com.chrome.devtools.json apenas no modo de desenvolvimento ao depurar um projeto local. Esse recurso não é destinado a ambientes de produção.
Conceder permissão para acessar arquivos locais
Por motivos de segurança, o Chrome exige permissão explícita do usuário para que um site acesse arquivos na sua rede local ou máquina. Quando o DevTools tentar se conectar ao seu projeto local usando devtools.json, você vai precisar conceder permissão para que o Chrome acesse o diretório do projeto. Essa solicitação de permissão segue as políticas de acesso à rede local do Chrome, que restringem solicitações de redes públicas para destinos locais, a menos que a permissão seja concedida. A capacidade de solicitar essa permissão é limitada a contextos seguros (HTTPS). Para desenvolvimento local, isso geralmente significa que localhost é tratado como um contexto seguro.
Criar e veicular um arquivo devtools.json
Para um projeto de front-end típico executado em um servidor de desenvolvimento local, é necessário configurar o servidor para responder à solicitação /.well-known/appspecific/com.chrome.devtools.json com o conteúdo JSON correto.
Confira como fazer isso:
- Gere um UUID:você vai precisar de um UUID v4. É possível gerar um usando ferramentas on-line ou um script.
- Determine a raiz do projeto:receba o caminho absoluto para o diretório raiz do projeto.
- Criar um endpoint:configure o servidor de desenvolvimento para processar solicitações GET para
/.well-known/appspecific/com.chrome.devtools.json. - Forneça o JSON:quando esse endpoint for atingido, forneça uma resposta JSON com o cabeçalho
Content-Type: application/jsone o conteúdodevtools.json.
O caminho workspace.root especificado no arquivo devtools.json precisa ser um caminho absoluto para o diretório raiz do projeto no sistema de arquivos local. Isso significa que o caminho vai variar de acordo com o sistema operacional (por exemplo, /Users/yourname/projects/my-app no macOS ou Linux ou C:\Users\yourname\projects\my-app no Windows) e a configuração específica do projeto. Considere adicionar o arquivo à lista de arquivos ignorados (por exemplo, .gitignore) para evitar o envio dele ao ambiente de produção.
É importante que seu servidor gere ou veicule esse caminho de forma dinâmica ou que você o configure corretamente para seu ambiente de desenvolvimento. Considere adicionar o arquivo à lista de arquivos ignorados (por exemplo, .gitignore) para evitar o check-in no ambiente de produção.
Exemplos
Há muitas maneiras de fornecer o arquivo devtools.json, dependendo da pilha de tecnologia do seu projeto.
Node.js e Express
Esse script executa um servidor Express mínimo. Ele veicula um arquivo JSON em /.well-known/appspecific/com.chrome.devtools.json que contém o caminho para projectRoot.. Ele aponta para a pasta em que o servidor é executado. Ajuste a variável projectRoot para apontar corretamente para o diretório raiz real do projeto, não necessariamente onde o script do servidor está localizado.
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}`);
});
Usar o script devtools-json-generator
Você pode usar generate-devtools-json para gerar o devtools.json.
Para gerar o arquivo devtools.json no diretório atual, execute:
npx generate-devtools-json
Ou, para gerar o arquivo em um diretório específico, transmita o diretório como um argumento:
npx generate-devtools-json /path/to/your/project
Leia mais sobre o devtools-json-generator na página inicial do projeto.
Integrações
Alguns frameworks de front-end e ferramentas de build oferecem plug-ins ou configurações para simplificar esse processo.
Vite
Para projetos baseados em Vite (incluindo SvelteKit), o vite-plugin-devtools-json é uma solução. Ele automatiza a geração e a veiculação do arquivo devtools.json de maneira dinâmica.
Para usar, instale o plug-in:
npm install -D vite-plugin-devtools-json
Em seguida, adicione ao seu 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
Se você usar ng serve para executar seu projeto Angular localmente (e a versão do @angular/cli for pelo menos 19.0.0), a CLI do Angular vai fornecer um middleware que veicula automaticamente o arquivo devtools.json correto.
Por exemplo, para criar e executar um novo aplicativo:
npm install -g @angular/cli
ng new my-first-angular-app
ng serve
Ao navegar até https://localhost:4200/.well-known/appspecific/com.chrome.devtools.json, você pode ver o arquivo JSON gerado.
Solução de problemas
Siga as dicas desta seção para resolver os problemas típicos relacionados à conexão automática do espaço de trabalho.
Remover uma pasta dos espaços de trabalho
Se uma pasta de projeto já estiver conectada automaticamente, você poderá removê-la manualmente das configurações do espaço de trabalho do DevTools:
- Abra o Chrome DevTools.
- Acesse a guia Origens.
- No painel à esquerda, selecione a subguia Espaços de trabalho.
- Clique com o botão direito do mouse na pasta do projeto indesejado e selecione Remover do espaço de trabalho.
Ignorar erros 404 no servidor
Se você não quiser usar esse recurso em um projeto específico e encontrar erros 404 na solicitação /.well-known/appspecific/com.chrome.devtools.json nos registros do servidor, ignore esses erros. A solicitação é inofensiva se o arquivo não for veiculado. Ou configure o servidor para responder com um status 404 para esse caminho específico sem registrar um erro.
Como desativar esse recurso no Chrome DevTools
Se você precisar desativar o recurso de descoberta automática de espaços de trabalho no Chrome DevTools, defina a flag do Chrome adequada:
- Abra o Chrome e navegue até
chrome://flags. - Pesquise Configurações do projeto do DevTools e defina como Desativado.
- Você também pode encontrar uma flag relacionada chamada DevTools Automatic Workspace Folders e desativá-la também.
- Reinicie o Chrome para que as mudanças entrem em vigor.
Resumo
Ao entender e usar o mecanismo devtools.json, você pode melhorar significativamente seu fluxo de trabalho de desenvolvimento local com o Chrome DevTools.