Inspecting the contents of AsyncStorage files on Mac

Background / Motivation #

The internal state of AsyncStorage can be crucial for debugging and testing React Native apps. Peel back the curtain and AsyncStorage is storing json files on your filesystem. Here is how to quickly find them and inspect them directly.

How to find the files #

First, define a variable to hold your package name #

We are going to be using a lot of commands that involve your package name. So to make copy/pasting easier for the rest of this post, we are going to set up a variable to hold your package name.

If you don't remember it - How to quickly find package name #

Run:

ls -l $HOME/Library/Developer/CoreSimulator/Devices/**/data/Containers/Data/Application/**/Library/Application\ Support

Look in the output for your package name. You probably recognize it - you just needed a quick reminder and a source for copy/paste :)

Once you have it #

Just run:

packageName="com.yourpackage.app"

In your shell before running the other commands here. You only need to run that once per shell session.

If you are on react-native-async-storage/async-storage #

For all commands in this section, replace "$packageName" with your bundle ID

If you want to see all devices you have AsyncStorage files for, run:

ls ~/Library/Developer/CoreSimulator/Devices/**/data/Containers/Data/Application/**/Library/Application\ Support/"$packageName"/ | grep -i RCT -C 1

If you want to find a specific device. #

xcrun simctl list | grep -i booted

This gives you a list of all simulators you have running. For example:

iPhone 14 Pro (0F0B25C2-7C34-45DA-815D-EE8F1CFC363C) (Booted)

Copy the ID:

0F0B25C2-7C34-45DA-815D-EE8F1CFC363C

And use it to run:

ls ~/Library/Developer/CoreSimulator/Devices/0F0B25C2-7C34-45DA-815D-EE8F1CFC363C/data/Containers/Data/Application/**/Library/Application\ Support/"$packageName"/ | grep -i RCT -C 1

That will find the async-storage files for that particular device. You can open that folder with finder/vscode/whatever and poke around to see the state of the files.

If you are on the deprecated AsyncStorage from react-native package #

Same steps as above, but the file path is a bit different:

ls ~/Library/Developer/CoreSimulator/Devices/**/data/Containers/Data/Application/**/Documents | grep -i RCT -C 1

What else can we do? #

Knowing these files are there also opens up more opportunities in addition to inspecting their contents. At the end of the day, these are just JSON files. So we can also modify them!

This gives us the ability to pre-set AsyncStorage to a specific state, which can be incredibly useful for testing and debugging.

For example, let's say you have a bug in your application that only occurs when the user's AsyncStorage is in a particular state. Debugging this can be quite tricky! However, with a bit of work we can give ourselves a reliable way to reproduce that state.

Understanding how the files are stored #

manifest vs individual files

• small values (under X kb) are stored in manifest directly
• bigger values in their own file
  • md5 hash for file name
  • recommend just figuring it out by looking at the values
  • but you can md5 the key too if you want
• link to asyncstorage docs for details

Manually setting the state #

You can manually set the files to be in any state you want. What you want to put in the files will depend on your app and situation. At the end of the day these are just JSON files. So put whatever content you need in the correct JSON files and it should work.

Automating AsyncStorage snapshots #

Outline:

1. Find the device you want to snapshot
2. Create and save a snapshot
3. Restore a snapshot