@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. You need a Free or Pro Buoy account. Sign in from your app's folder:
npx --package=@buoy-gg/core buoy login
Your browser opens buoy.gg. Click Allow. The CLI then writes a dev token. It works in dev builds for 30 days.
On Expo, the token goes in .env.development.local. Buoy reads it by itself in dev builds. You can also pass it in yourself:
import { Buoy } from "@buoy-gg/core";
Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
On React Native CLI, the token goes in .env.local as BUOY_KEY. React Native does not load that file by itself. Pass the token in with your app's own env setup. 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.
- Put the app into a recognizable test state and capture a named restore point.
- Change a disposable value through the app.
- Open the restore preview. Check additions, removals, overwrites, skipped items, and selected sources.
- 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 uses the sign-in from buoy login on your computer. Free has the basic MCP. Reading this tool from the MCP needs Pro.
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.