Extensões do Dart e Flutter DevTools

Um guia para criar ferramentas personalizadas no Dart e Flutter DevTools

Você já quis criar ferramentas para desenvolvedores de Dart e Flutter, mas não sabia por onde começar? Ou talvez não quisesse passar por todo o trabalho de estabelecer uma conexão com um app Dart ou Flutter em execução para acessar os dados de depuração? Mesmo que você tenha criado uma ferramenta de desenvolvimento, como implantá-la ou dar aos usuários acesso fácil a ela? Bem, temos boas notícias: agora você pode criar ferramentas para desenvolvedores sem todos esses obstáculos.

Com o novo framework de extensões do Dart & Flutter DevTools, você pode criar facilmente ferramentas para desenvolvedores que são fortemente integradas ao conjunto de ferramentas existente do DevTools. As extensões são construídas com Flutter web e aproveitam frameworks e utilitários existentes do DevTools para simplificar a experiência de criação de ferramentas.

Exemplo de extensão do DevTools para o package:foo
Exemplo de extensão do DevTools para o package:foo

Como funcionam as extensões do DevTools?

As extensões são distribuídas como parte de um pacote pub. Você pode adicionar uma extensão do DevTools a um pacote pub existente ou criar um novo pacote que forneça apenas uma extensão do DevTools. Nos dois casos, o usuário final precisa declarar uma dependência do pacote que fornece a extensão do DevTools para vê-la no DevTools.

Por exemplo, imagine que temos alguns package:foo, e este pacote fornece uma extensão do DevTools. Quando um usuário depende de package:foo no app dele, ele ganha automaticamente acesso à extensão do DevTools fornecida por este pacote. Quando o DevTools detecta que a extensão package:foo está disponível, com base em informações do app do usuário ou da IDE dele, uma nova aba “Foo” será adicionada ao DevTools, contendo as ferramentas de desenvolvimento fornecidas por package:foo.

Alguns exemplos de pacotes que adicionaram uma extensão do DevTools a um pacote existente são package:provider, package:patrol e package:drift.

Quais tipos de ferramentas são suportados?

Com o framework de extensões do DevTools, você pode criar muitos tipos de ferramentas, incluindo:

  • Ferramentas complementares para pacotes existentes

  • Novas ferramentas distribuídas como pacote próprio

  • Ferramentas que interagem com um app em execução

  • Ferramentas que não interagem com um app em execução

  • Ferramentas que interagem com arquivos de projeto abertos na IDE

  • Planejado para o futuro: ferramentas que interagem com o servidor de análise (vote nesta issue se quiser essa funcionalidade mais cedo!)

O framework de extensões do DevTools vem com recursos prontos que tornam a distribuição da sua extensão para os usuários simples:

  • Os usuários podem usar sua ferramenta a partir do DevTools no navegador

  • Os usuários podem usar sua ferramenta incorporada diretamente na IDE deles

  • Os usuários podem descobrir e abrir sua ferramenta a partir de IDEs compatíveis com Dart e Flutter

Agora vamos começar!

Escrevendo uma extensão do DevTools: um guia passo a passo

Antes de começar

O que você vai precisar:

  • SDK do Flutter >= 3.17.0–0.0.pre e SDK do Dart >= 3.2.

  • Um pacote Pub (existente ou novo) ao qual adicionar uma extensão do DevTools.

Para usar os pacotes mais recentes devtools_extensions e devtools_app_shared, é aceitável desenvolver sua extensão a partir do canal master ou beta do Flutter.

Passo 1: configure a hierarquia dos seus pacotes

Extensões independentes

Para uma extensão independente (uma extensão que não é distribuída como parte de um pacote pub existente), é aceitável incluir o código-fonte da extensão no mesmo pacote com o qual ela é distribuída. Isso simplifica o desenvolvimento e, como os usuários do seu pacote vão adicionar uma dependência ao seu pacote como dev_dependency, o tamanho do pacote não afetará o tamanho do app do usuário. A estrutura do seu pacote ficará assim:

my_new_tool
  extension/
    devtools/
      build/
        ...  # pre-compiled output of the Flutter web app under lib/
      config.yaml
  lib/  # source code for your extension Flutter web app
    src/
      ...

Como a extensão precisa ser construída como um app web Flutter, use flutter create para gerar o pacote da sua extensão do DevTools:

bash
flutter create --template app --platforms web my_new_tool

Agora, use o pacote my_new_tool para configurar sua extensão na próxima etapa.

Extensões complementares

Para uma extensão complementar (uma extensão distribuída como parte de um pacote pub existente), recomendamos colocar o código-fonte da extensão fora do seu pacote pub. Isso ajuda a manter o tamanho do pacote o menor possível, já que você vai querer evitar inflar o tamanho dos apps dos usuários que dependem do seu pacote. Esta é a estrutura de pacote recomendada:

foo/  # formerly the repository root of your pub package
  packages/
    foo/  # your pub package
      extension/
        devtools/
          build/
            ...  # pre-compiled output of foo_devtools_extension/lib
          config.yaml
    foo_devtools_extension/
      lib/  # source code for your extension Flutter web app

Passo 2: configure sua extensão

No pacote Dart que vai fornecer a extensão do DevTools aos usuários, adicione um diretório extension no nível raiz:

foo/
  extension/
  lib/
  ...

Dentro do diretório extension, crie a seguinte estrutura exatamente como mostrado:

extension/
  devtools/
    build/
    config.yaml

O arquivo config.yaml contém os metadados que o DevTools precisa para carregar a extensão:

yaml
name: foo
version: 0.0.1
issueTracker: <link_to_your_issue_tracker.com>
materialIconCodePoint: '0xe0b1'
requiresConnection: true  # optional field - defaults to true

Copie o conteúdo do arquivo config.yaml acima e cole no arquivo config.yaml que você acabou de criar no seu pacote. É importante usar exatamente o nome do arquivo e os nomes dos campos como mostrado, senão sua extensão pode não carregar no DevTools.

Para cada chave, preencha o valor apropriado para o seu pacote.

  • name: o nome do pacote ao qual esta extensão do DevTools pertence. O valor deste campo é usado na barra de título da página da extensão. [obrigatório]

  • version: a versão da sua extensão do DevTools. Este número de versão deve evoluir ao longo do tempo, à medida que você lança novos recursos da extensão. O valor deste campo é usado na barra de título da página da extensão. [obrigatório]

  • issueTracker: a URL do seu rastreador de issues. Quando o usuário clica no link “Reportar um problema” na interface do DevTools, ele é direcionado para esta URL. [obrigatório]

Barra de título da tela da extensão do DevTools
Barra de título da tela da extensão do DevTools
  • materialIconCodePoint: corresponde ao valor de codepoint de um ícone de material/icons.dart. Este ícone é usado na aba da extensão na barra de abas do DevTools no nível superior. [obrigatório]
Ícone da aba da extensão do DevTools
Ícone da aba da extensão do DevTools
  • requiresConnection: se a extensão requer um app Dart ou Flutter conectado para ser usada. Este é um campo opcional que terá como padrão true se não for especificado. [opcional]

Para a documentação mais atualizada da especificação config.yaml, veja extension_config_spec.md.

Agora é hora de construir sua extensão.

Passo 3: construa sua extensão

  1. Crie o app web Flutter.

Observação: pule esta etapa se estiver construindo uma extensão independente, já que você já fez isso ao configurar a hierarquia dos seus pacotes.

No diretório onde você quer que o código-fonte da sua extensão fique, execute o seguinte comando, substituindo foo_devtools_extension por <your_package_name>_devtools_extension:

shell
flutter create --template app --platforms web foo_devtools_extension
  1. Adicione a dependência package:devtools_extensions ao seu app web Flutter da extensão.
shell
flutter pub add devtools_extensions

Você provavelmente também vai querer adicionar uma dependência do package:devtools_app_shared, que contém serviços, utilitários e componentes de interface compartilhados para você usar ao construir sua extensão. Veja devtools_app_shared/example para exemplos de uso.

shell
flutter pub add devtools_app_shared
  1. Adicione o widget DevToolsExtension na raiz do seu app web Flutter.

Em lib/main.dart, adicione o seguinte:

dart
import 'package:devtools_extensions/devtools_extensions.dart';
import 'package:flutter/material.dart';
​
void main() {
  runApp(const DevToolsExtension());
}
​
class FooDevToolsExtension extends StatelessWidget {
  const FooDevToolsExtension({super.key});
​
  @override
  Widget build(BuildContext context) {
    return const DevToolsExtension(
      child: Placeholder(), // Build your extension here
    );
  }
}

O widget DevToolsExtension executa automaticamente toda a inicialização da extensão necessária para interagir com o DevTools. De qualquer lugar do seu app web da extensão, você pode acessar os globals:

  • extensionManager: um gerenciador para interagir com o DevTools ou com o framework de extensões.

  • serviceManager: um gerenciador para interagir com o serviço de VM conectado, se houver.

  • dtdManager: um gerenciador para interagir com o Dart Tooling Daemon, se houver.

Passo 4: depure sua extensão

Ao desenvolver e manter sua extensão do DevTools, você vai querer executar, depurar e testar seu app web Flutter da extensão. Você tem algumas opções diferentes para isso, descritas abaixo.

Para fins de depuração, você provavelmente vai querer usar o “ambiente simulado do DevTools”. Trata-se de um ambiente que permite construir sua extensão sem precisar desenvolvê-la como um iFrame incorporado ao DevTools. Executar sua extensão desta forma a envolve com um ambiente que simula a conexão entre o DevTools e a extensão. Também dá acesso ao hot restart e a um ciclo de desenvolvimento mais rápido.

Depurando uma extensão com o ambiente simulado do DevTools
Depurando uma extensão com o ambiente simulado do DevTools
  1. Sua extensão do DevTools.

  2. O URI do serviço de VM de um app de teste com o qual sua extensão do DevTools vai interagir. Este app deve depender do pacote pai da sua extensão (package:foo neste exemplo).

  3. Botões para executar ações que o usuário pode disparar a partir do DevTools.

  4. Logs mostrando as mensagens que serão enviadas entre sua extensão e o DevTools.

O ambiente simulado é habilitado pelo parâmetro de ambiente use_simulated_environment. Para executar seu app web da extensão com essa flag habilitada, adicione uma configuração ao seu arquivo launch.json no VS Code:

json
{
    // ...
    "configurations": [
        // ...
        {
            "name": "foo_devtools_extension + simulated environment",
            "cwd": "packages/foo_devtools_extension",
            "request": "launch",
            "type": "dart",
            "args": [
                "--dart-define=use_simulated_environment=true"
            ],
        },
        // ...
    ]
}

ou inicie seu app pela linha de comando com a flag adicionada:

shell
flutter run -d chrome - dart-define=use_simulated_environment=true

Opção B: use um ambiente real do DevTools

Quando você tiver desenvolvido sua extensão até o ponto em que estiver pronto para testar suas mudanças em um ambiente real do DevTools, precisará executar uma série de etapas de configuração:

  1. Desenvolva sua extensão até o ponto em que estiver pronto para testar as mudanças em um ambiente real do DevTools. Construa seu app web Flutter e copie os assets gerados de your_extension_web_app/build/web para o diretório extension/devtools/build do seu pacote pub.

Use o comando build_and_copy de package:devtools_extensions para ajudar com esta etapa.

shell
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions build_and_copy --source=. --dest=path/to/your_pub_package/extension/devtools

Observação: se você estiver usando a estrutura de pacote recomendada acima para adicionar uma extensão a um pacote pub existente, o valor de --dest deve ser ../your_pub_package/extension/devtools.

Para garantir que sua extensão esteja configurada corretamente para ser carregada no DevTools, execute o comando validate de package:devtools_extensions. O argumento --package deve apontar para a raiz do pacote Dart com o qual esta extensão será publicada.

shell
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions validate --package=path/to/your_pub_package
  1. Prepare um ambiente de teste com uma dependência do seu pacote pub que fornece a extensão.

    No projeto Dart ou Flutter em que você está adicionando uma dependência do seu pacote, adicione uma dependência path que aponte para o código-fonte local do seu pacote (o pacote que contém o diretório extension/devtools/ com os assets da sua extensão). Depois disso, execute pub get no pacote.

    • Se sua extensão requer um app em execução, então você vai precisar executar o app que depende da sua extensão.

    • Se sua extensão não requer um app em execução, então você vai precisar abrir o projeto Dart ou Flutter de teste que depende do seu pacote em uma IDE compatível (VS Code ou IntelliJ / Android Studio).

  2. Inicie o DevTools de uma das seguintes formas:

    • Se sua extensão requer um app em execução, você pode abrir o DevTools pelo URI que foi impresso na linha de comando quando você executou o app de teste, ou pela IDE em que executou o app de teste.

    • Se sua extensão não requer um app em execução, você pode abrir o projeto Dart ou Flutter de teste que depende do seu pacote em uma IDE compatível (VS Code ou IntelliJ / Android Studio). Abra o DevTools pela IDE para ver sua extensão no navegador.

    • Se você precisar de alterações locais ou não lançadas do DevTools, vai precisar compilar e executar o DevTools a partir do código-fonte. Veja o CONTRIBUTING.md para um guia de como fazer isso. Você vai precisar compilar o DevTools com o servidor e o front-end para testar extensões — veja as instruções.

  3. Depois de abrir o DevTools, você deve ver uma aba na barra de aplicativos do DevTools para a sua extensão. O estado habilitado ou desabilitado da sua extensão é gerenciado pelo DevTools, que o expõe em um menu “Extensions”, disponível nos botões de ação no canto superior direito da tela.

Botão do menu de extensões do DevTools
Botão do menu de extensões do DevTools
Menu de extensões do DevTools
Menu de extensões do DevTools

Passo 5: publique seu pacote com uma extensão do DevTools

Para que um pacote forneça uma extensão do DevTools aos seus usuários, ele precisa ser publicado com o conteúdo esperado no diretório your_pub_package/extension/devtools/ (veja as instruções de configuração acima).

  1. Garanta que o arquivo extension/devtools/config.yaml exista e esteja configurado de acordo com as especificações acima. Você pode executar o comando validate a partir de package:devtools_extensions para verificar.
bash
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions validate --package=path/to/pkg_providing_your_extension_assets
  1. Use o comando build_and_copy fornecido por package:devtools_extensions para compilar sua extensão e copiar a saída para o diretório extension/devtools:
shell
cd your_extension_web_app;
flutter pub get;
dart run devtools_extensions build_and_copy --source=. --dest=path/to/your_pub_package/extension/devtools

Depois, publique seu pacote no pub.dev: flutter pub publish. Ao executar pub publish, você verá um aviso se não tiver o arquivo config.yaml e um diretório build não vazio, como exigido.

Para mais orientações sobre a publicação do seu pacote, veja o package:devtools_extensions guia de publicação.

Conclusão

Pronto! Agora, quando um usuário depender da versão mais recente do seu pacote, ele terá acesso automaticamente às ferramentas que você fornece na sua extensão do DevTools.

Para problemas e pedidos de funcionalidades, abra uma issue no rastreador de issues do DevTools.

Para suporte geral e acesso à comunidade de autores de extensões do DevTools, confira o canal #devtools-extension-authors no Discord (você precisará entrar primeiro no servidor do Flutter no Discord).

Mais do Flutter