flutter_storage_inspector 0.1.0

A debug-only Flutter package for inspecting, searching, editing, exporting, and managing local application storage with a developer-focused UI.

flutter_storage_inspector

flutter_storage_inspector is a debug-only Flutter package for inspecting, searching, editing, exporting, and managing local application storage from a developer-focused Material 3 interface.

Project Overview

Flutter developers often need quick visibility into local storage while debugging app state, migrations, feature flags, and cached user data. This package provides a reusable inspector that can be attached to an app with minimal setup and automatically stays out of release builds.

Features

• Debug-only wrapper with automatic release-build suppression.
• Overlay and full-screen presentation modes.
• Floating launcher bubble, keyboard shortcut, and optional gesture access.
• Search, filter, sort, refresh, edit, delete, clear, and export actions.
• JSON tree viewer for structured values.
• Responsive Material 3 layout for mobile, tablet, desktop, and web.
• Modular adapter architecture for supported storage backends.

Installation

dependencies:
  flutter_storage_inspector: ^0.1.0

Quick Start

import 'package:flutter/foundation.dart';
import 'package:flutter_storage_inspector/flutter_storage_inspector.dart';

runApp(
  StorageInspector(
    enabled: kDebugMode,
    adapters: StorageInspectorAdapters.defaults(
      getStorageContainers: ['inspector_demo'],
      hiveBoxes: ['inspector_demo_box'],
    ),
    child: const MyApp(),
  ),
);

You can also attach the inspector with MaterialApp.builder:

MaterialApp(
  builder: StorageInspector.builder(
    enabled: kDebugMode,
    adapters: StorageInspectorAdapters.defaults(),
  ),
)

Example Usage

The example/ app demonstrates:

• Package integration with a real Flutter application shell.
• Seeded data for multiple storage adapters.
• Overlay and full-screen inspector access.
• Safe debug-time data mutation and refresh flows.

Screenshots

Screenshot placeholders will be added after the first public repository is set up and visual assets are captured.

GIF

Animated demo placeholder.

Architecture Overview

The package is organized around a small set of composable layers:

• adapters/: storage-specific read, write, delete, clear, and watch logic.
• controllers/: refresh, filter, sort, and mutation orchestration.
• models/: immutable state and configuration objects.
• ui/ and widgets/: reusable inspector screens and presentation widgets.
• utils/ and themes/: value formatting, export helpers, and visual tokens.

Supported Storage Adapters

• SharedPreferencesAdapter
• SharedPreferencesAsyncAdapter
• GetStorageAdapter
• FlutterSecureStorageAdapter
• HiveAdapter

FAQ

Does the inspector run in release builds?

No. StorageInspector returns the child app unchanged when kReleaseMode is true.

Do I need to register every key manually?

No. The built-in adapters read keys directly from their configured storage backends.

Why do Hive boxes still need configuration?

Hive only exposes boxes that are already known and opened by the application. The inspector reads the boxes you explicitly register.

Roadmap

• Add additional export destinations beyond clipboard-based flows.
• Add import and restore workflows.
• Expand adapter support for more local persistence libraries.
• Add richer visual assets and package documentation examples.

Contributing

See CONTRIBUTING.md for development setup, validation commands, and pull request guidance.

License

This project is licensed under the MIT License. See LICENSE.