Custom Tools

Implement DebugTool to add an app-specific screen alongside the built-in tools, then pass it via DebugToolkitConfig.extraTools.

The DebugTool interface

abstract class DebugTool {
  String get id;                       // stable, unique id
  String get title;                    // menu row + page title
  String? get subtitle => null;        // one-line description (optional)
  IconData get icon;                   // leading icon
  Widget buildPage(BuildContext context); // the pushed page
}

buildPage is pushed onto the toolkit’s own navigator, so it must provide its own scaffold. Use DebugScaffold for a consistent look (it gives you the app bar, an automatic back button and a SafeArea body).

Example: a “Feature flags” tool

import 'package:carp_debug_flutter/carp_debug_flutter.dart';
import 'package:flutter/material.dart';

class FeatureFlagsTool implements DebugTool {
  const FeatureFlagsTool();

  @override
  String get id => 'feature-flags';
  @override
  String get title => 'Feature Flags';
  @override
  String? get subtitle => 'Toggle experimental features';
  @override
  IconData get icon => Icons.flag;

  @override
  Widget buildPage(BuildContext context) => const _FeatureFlagsPage();
}

class _FeatureFlagsPage extends StatefulWidget {
  const _FeatureFlagsPage();
  @override
  State<_FeatureFlagsPage> createState() => _FeatureFlagsPageState();
}

class _FeatureFlagsPageState extends State<_FeatureFlagsPage> {
  @override
  Widget build(BuildContext context) {
    return DebugScaffold(
      title: 'Feature Flags',
      body: ListView(
        children: [
          for (final flag in FeatureFlags.all)
            SwitchListTile(
              title: Text(flag.name),
              value: flag.enabled,
              onChanged: (v) => setState(() => flag.enabled = v),
            ),
        ],
      ),
    );
  }
}

Register it:

DebugToolkitConfig(
  // ...built-in config...
  extraTools: const [FeatureFlagsTool()],
);

Tip

Custom tools are appended after the built-in tools, in the order you provide them.

Reusing toolkit infrastructure

Custom tool pages can use the same building blocks the built-in tools use:

DebugScaffold

Consistent page chrome (title, actions, body, floatingActionButton).

DebugEnv

Read / write launch-argument overrides from your tool.

DebugLog

DebugLog.instance.log(...) to emit lines into the Logs tool.

KeyValueStore / DebugDatabase

Reuse the data-source adapters to read app storage.