app_debugger_storage Pro

Docs/Bricks/app_debugger_storage

Tier

Proversion 1.2.4

Command

archipelago generate app_debugger_storage

Generates

• features/app_debugger_storage/app_debugger_storage
• features/app_debugger_storage/app_debugger_storage_api
• features/app_debugger_storage/app_debugger_storage_noop

Generates first

app_debuggerwhen needed and missing, so there is nothing to install first

Depends on

shared_identifiersgenerate these first

Tutorial

Step-by-step: add app_debugger_storage to a project

Storage inspector sub-brick for app_debugger. Adds a Storage tool showing a categorised breakdown of app storage (app bundle, internal data, cache, other). Full native inspection on Android; iOS returns a sandbox-limited stub. Automatically swapped to a no-op stub in production-flavor builds via build_prepare.

Variables

This brick has no generation-time variables.

Install

Interactive

archipelago generate app_debugger_storage

Non-interactive (CI)

archipelago generate app_debugger_storage --config my_config.json

Prerequisites

app_debugger is generated first when the project lacks it. It owns di/debug_tools.dart, whose archipelago:debug_panel_pages marker this brick's post_gen hook patches with an eager GetIt.I<StorageInspectorSDK>() resolution. The marker moved between app_debugger versions, so the hook uses the first file that has it: app_debugger's lib/src/di/debug_tools.dart (2.0.0 and later), its lib/src/app_debugger_sdk_impl.dart (1.3.0 to 1.15.x), then the app's lib/bootstrap.dart (older), and adds the imports and path dependencies to that package. A file that already resolves the SDK is left as it is. If no file has the marker, pre_gen prints the lines to add and stops before it writes any file. See app_debugger's page for the shared-Navigator architecture.

Generated Structure

features/
└── app_debugger_storage/
    ├── app_debugger_storage_api/
    │   └── lib/src/
    │       ├── storage_inspector_sdk.dart
    │       └── models/               # StorageBreakdown, StorageCategory, StorageItem
    ├── app_debugger_storage/
    │   ├── android/src/main/kotlin/  # AppDebuggerStoragePlugin, StorageAnalyzer
    │   ├── ios/Classes/              # Sandbox-limited iOS stub
    │   └── lib/src/
    │       ├── storage_inspector_sdk_impl.dart
    │       ├── storage_inspector_method_channel.dart
    │       └── storage_inspector_page.dart
    └── app_debugger_storage_noop/
        └── lib/src/di/

Public API

final sdk = getIt<StorageInspectorSDK>();

final breakdown = await sdk.captureBreakdown();
breakdown.totalBytes;       // sum across all four buckets
breakdown.dataItems;        // List<StorageItem> — files, databases, shared_prefs, code cache
breakdown.note;             // non-null on iOS: explains the sandbox limitation

final path = await sdk.exportAsJson(); // writes JSON to temp dir, opens the share sheet

StorageBreakdown groups results into four buckets — appBundleItems, dataItems, cacheItems, otherItems — each a List<StorageItem>. Every StorageItem also carries a StorageCategory (appBundle, files, databases, sharedPrefs, codeCache, internalCache, externalCache, externalFiles, obb, other) so the UI/export can still show the finer-grained Android source path.

Platform Support

Platform	Behaviour
Android	Full directory walk via native Kotlin StorageAnalyzer, one level of children per category (APK, filesDir, databases, shared_prefs, code cache, internal/external cache, external files, OBB).
iOS	Sandbox-limited stub. Only the app bundle size is available via FileManager. Data, cache, and external directories cannot be inspected due to iOS sandbox restrictions — StorageBreakdown.note explains this in the UI.

Native Plugin

The Android plugin (AppDebuggerStoragePlugin) registers MethodChannel('archipelago/app_debugger_storage') via the FlutterPlugin interface. The iOS plugin registers the same channel and returns the sandbox-limited response described above.

DI & Wiring

• AppDebuggerStoragePackageModule is declared under archipelago: di_modules and registered into the app injector by post_gen.
• StorageInspectorSDKImpl is @Singleton(as: StorageInspectorSDK) (eager since 1.1.11); it registers itself with FeatureSDKRegistry and registers StorageInspectorPage with DebuggerPanelPageRegistry in its constructor; post_gen also adds the eager resolution call (see Prerequisites).
• app_debugger_storage_api is added as a dependency of app_debugger itself (not the host app) — it's the only place StorageInspectorSDK is referenced for the eager-resolution call.

Dependencies

app_debugger_storage package: share_plus ^13.3.0, path_provider ^2.1.6 (debug impl only — the noop and API packages don't need them).

Android: File Sharing

The export feature uses share_plus, which auto-registers a FileProvider in its own AndroidManifest. Manifest merger combines this with your app's manifest automatically — no manual setup needed for typical Flutter apps.

Limitations

• iOS inspection is bundle-size-only by design (sandbox restriction), not a gap to be fixed.
• android/build.gradle hardcodes its AGP/Kotlin/compileSdk/minSdk versions rather than reading a version catalog (per CHANGELOG 1.1.7 — no generated scaffold provides one at a path this plugin could reach).

Changelog

Run archipelago brick info app_debugger_storage to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.