@buoy-gg/time-machine

Save and restore supported client state while testing a React Native app. A restore point can include registered storage, Redux, Zustand, Jotai, and the React Query cache. Review the restore preview before applying changes.

Install

npm install @buoy-gg/core @buoy-gg/time-machine

Account setup

Start in a development build with a Free or Pro Buoy account key. From the app directory:

npx --package=@buoy-gg/core buoy login

For Expo, initialize Buoy with the key written to .env.local:

import { Buoy } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

For React Native CLI, pass the key through your app's environment configuration; .env.local is not loaded automatically. Keep the menu inside the providers used by your app. Restart the development server after installing packages. See the Quick Start for the complete root component.

Use a restore point

Mount FloatingDevTools in your app. Buoy discovers this package. Install and configure the source tools for the state you want to capture: Storage, Redux, Zustand, Jotai, or React Query.

1. Put the app into a recognizable test state and capture a named restore point.
2. Change a disposable value through the app.
3. Open the restore preview. Check additions, removals, overwrites, skipped items, and selected sources.
4. Restore, then read the value from the app and inspect the per-source results.

To repeat one restore many times, tap Action bar in the tool header or swipe a restore point and choose Bar. The tool minimizes and a floating strip stays over the app with one restore point armed: tap to restore it (long press for state only, without changing screens), + to name, capture and arm a new point, the chevron beside the name picks another. Each restore from the strip saves a "Before last restore" copy first and offers Undo for ten seconds. The strip's picker has a "Reload the app after restoring" switch for screens that read their state from storage only on mount (a cart kept in a React context, for example): a live restore cannot reach useState, a reload can. The strip returns after a reload and can be dragged or hidden at the screen edge.

Live restore applies supported state in place. Restore + reload writes persisted storage and reloads JavaScript so the app can initialize from that storage. Optional Expo Router URL restoration does not recreate the entire navigation back stack.

Each tile in the Sources strip is a switch. A source switched off is left out of every capture and restore, so a store the app cannot survive having replaced (a Zustand store holding live handles, for example) can stay untouched while the rest of the state round-trips.

Restore limits

Restoring can remove keys absent from the snapshot. Exclude values you need to preserve in the preview. Read-only or unsupported values are skipped and reported. SecureStore and MMKV require the same registered keys and instances as the Storage tool.

Backend changes, component-local useState, and in-flight requests are not restored. A restored cart or session remains subject to backend validation. Redux needs a supported full-state restore integration; writable Jotai atoms can be restored, while read-only atoms recompute. React Query mutation history is not replayed.

API

For explicit registration, use the exported createTimeMachineTool or timeMachineToolPreset. Advanced integrations can use timeMachineStore, RestoreOptions, and RestoreOutcome.

See the Time Machine guide for source-specific behavior, persistent exclusions, and restore results.

Desktop and MCP

React Native connections require @buoy-gg/external-sync. Follow the Desktop connection guide, sign in to Desktop separately, and confirm the selected device. MCP also needs a process account and Pro access.

Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.

Web support (unreleased)

In dev builds, a saved bar opens on web boot.

Register this package’s /web namespace in FloatingDevTools modules to use its shared panels and actions in a browser app. The browser build is available in this checkout and has not been published yet. See the web setup guide for registration, dependencies, and browser boundaries.