buoy_storage

Inspect shared_preferences and storage backends you register with Buoy.

Requirements

Use a Flutter debug build and a Free or Pro Buoy account key. These packages require Dart 3.9 or later, below 4.0, and Flutter 3.27 or later; your Flutter installation must satisfy both constraints. The Buoy widget does not start its tools in profile or release builds, including with Pro.

Install and register

flutter pub add buoy_storage

This example registers the standalone package. In an existing app, keep your screens and providers and apply the registration and builder changes to that app. Complete the tool-specific integration below before testing capture.

import 'package:buoy_storage/buoy_storage.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (kDebugMode) registerBuoyStorage();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => BuoyDevTools(
        licenseKey: const String.fromEnvironment('BUOY_KEY'),
        child: child ?? const SizedBox.shrink(),
      ),
      home: const Scaffold(body: Center(child: Text('Buoy test app'))),
    );
  }
}

Get a key from your Buoy account, then run:

flutter run --dart-define=BUOY_KEY=YOUR_LICENSE_KEY

If you already use the buoy umbrella, it registers the panel; keep its builder and complete the app integration below. For a complete umbrella setup, see the Flutter Quick Start.

Monitoring and backends

shared_preferences has no change stream. Writes through BuoyPrefs can produce immediate events. Polling compares snapshots while monitoring is enabled; it can miss intermediate changes between polls.

Secure storage and MMKV need adapters for your storage plugin. Register your existing implementations with registerBuoySecureBackend and registerBuoyMmkvBackend. The package does not install those native storage plugins for you.

BuoySecureBackend.keys() supplies key descriptors. Keys requiring authentication are listed without automatic value reads. BuoyMmkvBackend.snapshot() supplies instances and entries. Review the exported Dart interfaces when implementing adapters; the conceptual shapes in a UI are not Dart map return types.

Use the Storage guide for backend integration and supported actions. Editing or clearing storage changes the running app's data.

Required keys

Pass required keys when registering Storage. The same declarations validate the local browser and reach Desktop through the getRequiredKeys action.

if (kDebugMode) {
  registerBuoyStorage(requiredKeys: const [
    RequiredStorageKey(
      key: 'theme',
      storageType: 'async',
      expectedValue: 'dark',
    ),
    RequiredStorageKey(
      key: 'auth_token',
      storageType: 'secure',
      expectedType: 'string',
    ),
  ]);
}

Use async, secure, or mmkv for storageType. Omitting it applies the declaration to every registered backend. Checks distinguish missing keys, wrong values, and wrong types. A required secure key can be read by name even when it is absent from the backend's key list. Keys marked requireAuthentication in that list remain unread and are shown as protected.

Calling registerBuoyStorage() again without requiredKeys preserves the configuration, including when the umbrella registers the tool. Pass an empty list to clear it.

Check the integration

Create a disposable preference, inspect it, edit it, and read it back from your app. Delete the test key when finished.

Desktop and MCP

Open Buoy Desktop, sign in, and select the connected device. The default broker port is 42831. The iOS Simulator uses localhost; the Android emulator maps localhost to its host address. For a physical device, set socketUrl: 'http://YOUR_COMPUTER_LAN_IP:42831' on BuoyDevTools and use a network that can reach your computer.

MCP needs separate process account configuration and Pro access. Remote capabilities depend on each tool's adapter. Account validation makes network requests, and device sessions can cross your LAN. See Telemetry for data-flow details.

Full Storage guide