Follow the instructions below to get started, and use the end-to-end example for reference.
DevTools extensions must be written as Flutter web apps. This is because DevTools embeds extensions in an iFrame to display them dynamically in DevTools.
To add an extension to your Dart package, add a top-level extension
directory:
foo_package extension/ lib/ ...
Under this directory, create the following structure:
extension devtools/ build/ config.yaml
The config.yaml
file contains metadata that DevTools needs in order to load the extension. Copy the config.yaml
file below and fill in the approproate value for each key. The material_icon_code_point
field should correspond to the codepoint value of an icon from material/icons.dart.
name: foo_package issue_tracker: <link_to_your_issue_tracker.com> version: 0.0.1 material_icon_code_point: '0xe0b1'
Now it is time to build your extension.
Only the pre-compiled output of your extension needs to be shipped with your pub package in order for DevTools to load it. To keep the size of your pub package small, we recommend that you develop your DevTools extension outside of your pub package. Here is the recommended package structure:
foo_package/ # formerly the repository root of your pub package packages/ foo_package/ # your pub package extension/ devtools/ build/ ... # pre-compiled output of foo_package_devtools_extension config.yaml foo_package_devtools_extension/ # source code for your extension
From the directory where you want your extension source code to live, run the following command, replacing foo_package_devtools_extension
with `<your_package_name>_devtools_extension``:
flutter create --template app --platforms web foo_package_devtools_extension
In foo_package_devtools_extension/pubspec.yaml
, add a dependency on devtools_extensions
:
devtools_extensions: ^1.0.0
In lib/main.dart
, place a DevToolsExtension
widget at the root of your app:
import 'package:devtools_extensions/devtools_extensions.dart'; void main() { runApp(const FooPackageDevToolsExtension()); } class FooPackageDevToolsExtension extends StatelessWidget { const FooPackageDevToolsExtension({super.key}); @override Widget build(BuildContext context) { return const DevToolsExtension( child: FooDevToolsExtension(), ); } }
The DevToolsExtension
widget automatically performs all extension initialization required to interact with DevTools. From anywhere your extension web app, you can access the globals extensionManager
and serviceManager
to send messages and interact with the connected app.
Use package:devtools_app_shared for access to service managers, common widgets, DevTools theming, utilities, and more. See devtools_app_shared/example for sample usages.
For debugging purposes, you will likely want to use the “simulated DevTools environment”. This is a simulated environment that allows you to build your extension without having to develop it as an embedded iFrame in DevTools. The simulated environment is enabled by an environment parameter use_simulated_environment
.
To run your extension web app with this flag enabled, add a configuration to your launch.json
file in VS code:
{ ... "configurations": [ ... { "name": "foo_devtools_extension + simulated environment", "program": "foo_package/extension/foo_devtools_extension/lib/main.dart", "request": "launch", "type": "dart", "args": [ "--dart-define=use_simulated_environment=true" ], }, ] }
or launch your app from the command line with the added flag:
flutter run -d chrome --dart-define=use_simulated_environment=true
To use a real DevTools environment, you will need to perform a series of setup steps:
your_extension_web_app/build
to your pub package's extension/devtools/build
directory.Use the build_extension
command from package:devtools_extensions
to help with this step.
cd your_extension_web_app && flutter pub get && dart run devtools_extensions build_and_copy \ --source=path/to/your_extension_web_app \ --dest=path/to/your_pub_package/extension/devtools
Prepare and run a test application that depends on your pub package. You'll need to change the pubspec.yaml
dependency to be a path
dependency that points to your local pub package source code. Once you have done this, run pub get
, and run the application.
Start DevTools:
Note: you'll need to build DevTools with the server and the front end to test extensions - see instructions.
<TODO: insert version>
, you can launch the DevTools instance that was just started by running your app (either from a url printed to command line or from the IDE where you ran your test app). You can also run dart devtools
from the command line.Connect your test app to DevTools if it is not connected already, and you should see a tab in the DevTools app bar for your extension. The enabled or disabled state of your extension is managed by DevTools, which is exposed from an “Extensions” menu in DevTools, available from the action buttons in the upper right corner of the screen.