@tcbs/realm-inspector

Graphical Realm inspector tooling for TCBS-based applications.

@tcbs/realm-inspector helps developers inspect local Realm data safely during development. It supports pulling fresh snapshots, exploring schemas, and browsing paginated records through a local UI.

Table of Contents

• Why This Package Exists
• Package Status
• Requirements
• Install (Dev)
• Quick Start
• Tutorial: End-to-End Usage
• Command Reference
• Encrypted Realm Support
• Best Practices
• Security Guidance
• Production Checklist
• Troubleshooting
• Credits
• Support

Why This Package Exists

Realm data debugging often requires manual path hunting and ad-hoc scripts.

This package standardizes that workflow:

1. pull latest DB snapshot
2. inspect schema
3. browse records with limit/offset
4. repeat quickly while developing

Package Status

Current version (0.1.x) includes:

• local inspector UI served by CLI
• snapshot refresh workflow for Android and iOS Simulator
• snapshot list + schema + record browsing APIs
• encrypted key input support for browsing encrypted snapshots

Planned enhancements:

• field-level redaction defaults for sensitive data
• record export and comparison workflows
• deeper query/filter controls in UI

Requirements

• Node.js >=18
• development environment with either:
  • Android emulator/device with adb
  • iOS simulator with xcrun
• realm installed in the consuming project for schema and record browsing

Install (Dev)

npm i -D @tcbs/realm-inspector @tcbs/core @tcbs/data-realm

For schema and record browsing, ensure your project also has realm installed.

npm i realm

Run

tcbs-realm-inspector open

Tutorial: End-to-End Usage

1) Add script in your app

{
	"scripts": {
		"tcbs:inspect": "tcbs-realm-inspector"
	}
}

2) Open inspector UI

npm run tcbs:inspect

3) Refresh latest DB

Use Refresh DB in UI or run CLI refresh command directly.

4) Inspect data

In the UI:

1. choose snapshot
2. choose schema
3. set limit/offset
4. load records

Command Reference

# Open UI (auto opens browser)
tcbs-realm-inspector open

# Open UI without launching browser
tcbs-realm-inspector open --no-open-browser

# Pull and print refresh result (auto-detect platform when possible)
tcbs-realm-inspector refresh-db

# Use a custom project root
tcbs-realm-inspector open --project-root /path/to/project

# Pull from Android emulator/device app sandbox (debuggable app)
tcbs-realm-inspector refresh-db --platform android --android-package com.example.app

# Pull from iOS simulator app container
tcbs-realm-inspector refresh-db --platform ios --ios-bundle-id com.example.app

# Optional custom in-container realm paths
tcbs-realm-inspector refresh-db --platform android --android-package com.example.app --android-realm-path files/custom.realm
tcbs-realm-inspector refresh-db --platform ios --ios-bundle-id com.example.app --ios-realm-path Documents/custom.realm

Encrypted Realm Support

You can provide encryption key by CLI option, key file, or environment variable.

# Use encrypted Realm key from CLI
tcbs-realm-inspector open --platform android --android-package com.example.app --encryption-key-hex <128-char-hex>

# Use encrypted Realm key from file
tcbs-realm-inspector open --encryption-key-file ./.tcbs/realm-key.txt

# Use encrypted Realm key from env
TCBS_REALM_ENCRYPTION_KEY_HEX=<128-char-hex> tcbs-realm-inspector open

Expected key format:

• hex string only
• exactly 128 hex characters (64 bytes)

Best Practices

1. Install inspector as development-only dependency.
2. Keep inspector workflows out of production builds and release scripts.
3. Use explicit platform flags in CI/local scripts for deterministic behavior.
4. Keep DB path conventions documented per project.
5. Keep encryption keys in secure env/secret files, not committed source.
6. Use snapshot directory cleanup policies for large teams.

Security Guidance

• Treat pulled snapshots as sensitive data.
• Do not upload snapshots to public channels.
• Store key files outside tracked source control.
• Consider adding gitignore rules for .tcbs/realm-snapshots and key files.

Production Checklist

• [ ] Installed as dev dependency only
• [ ] Not used in production runtime paths
• [ ] Snapshot directories excluded from source control
• [ ] Encryption keys loaded from env/secure files only
• [ ] Team docs define approved local debugging workflow

Troubleshooting

realm package missing

Install in consuming app:

npm i realm

Android refresh fails with run-as error

• ensure app is debuggable
• verify package name passed to --android-package
• verify realm path inside app sandbox

iOS simulator container cannot be resolved

• boot a simulator
• ensure app is installed and launched at least once
• verify bundle id passed to --ios-bundle-id

Snapshot opens but schema read fails

• verify encryption key
• verify snapshot is fully copied and not truncated
• ensure Realm version compatibility

Credits

Core dependencies and ecosystem references:

• realm
• @tcbs/core
• @tcbs/data-realm

Support

If this package helps your workflow:

1. Star the repository.
2. Share bug reports with platform details and command used.
3. Contribute redaction/filter improvements.

Professional tooling quality improves fastest with field feedback from real projects.