expo / atlas

Visualize React Native bundles to understand and optimize your app.

Expo Atlas

Inspect your Metro bundle, on module level.

Warning

This project is unstable and might not work for your project.

🚀 How to use it

Atlas is built into Expo starting from SDK 51, and enabled when defining the environment variable EXPO_UNSTABLE_ATLAS=true.

You can use Atlas with two Expo commands:

• $ expo start → Start a local dev server, Atlas will listen to any change within your project.
• $ expo export → Export your app to Android, iOS, or web. Atlas will generate the atlas.jsonl file.

Using $ expo start

When enabling Atlas with the local dev server, you can access Atlas on http://localhost:8081/_expo/atlas. This shows you all information from the bundle loaded during development.

$ EXPO_UNSTABLE_ATLAS=true npx expo start

Tip

Expo start runs in development mode by default. If you want to see a production bundle of your app, you can start the local dev server in production mode: $ expo start --no-dev.

Using $ expo export

When enabling Atlas during exports, Expo generates the .expo/atlas.json file in your project. This file contains all bundle information, including the actual source code of individual files. You can open the Atlas file through npx expo-atlas [path/to/atlas.jsonl].

# Export the app for all platforms
$ EXPO_UNSTABLE_ATLAS=true npx expo export --platform all

# Open Atlas using the default `.expo/atlas.jsonl` path
$ npx expo-atlas
# Open Atlas from a shared file
$ npx expo-atlas ./path/to/atlas.jsonl

🏛️ Project structure

• apps/example — A default Expo project, with Atlas enabled by default
• packages/expo-atlas — The core package of Atlas, including Metro data handling and the CLI command
• packages/expo-atlas-ui — The web-only Expo project representing the UI of Atlas

🧑‍💻 Contributing to Atlas

Atlas is open source and contributions are welcome.

🏗️ Preparing the repository

• Clone this repository
• $ bun install — Atlas uses Bun's package manager, ensure you have it installed

🎨 Changing the Atlas UI

If you need to change anything related to the Atlas UI, you need to:

• $ bun start — This builds expo-atlas and starts expo-atlas-ui with a default fixture
• $ open http://localhost:8081 — To view expo-atlas-ui in your browser
• Make any change in expo-atlas-ui

📊 Changing the Atlas data

If you need to change anything related to extracting data from Metro, you need to:

• $ cd packages/expo-atlas — Make the changes in expo-atlas
• $ bun start — Build expo-atlas on any change
• Open another terminal
• $ cd apps/example — Atlas has a default Expo project to experiment with
• $ bun start — The example project automatically enables Atlas through apps/example/.env
  • $ bun expo export — The example project can also export an .expo/atlas.jsonl file
  • $ bun expo-atlas — When exporting an .expo/atlas.jsonl file, you can open Atlas using this export

📦 Releasing a new version

If you need to release a new version of Atlas, you need to:

• Make sure you have no uncomitted changes and have checked out main
• Update the package version in expo-atlas/package.json
• Commit the new version to main
• $ bun install — Make sure to install all dependencies
• $ bun run build — Build both expo-atlas and expo-atlas-ui
• $ cd packages/expo-atlas && npm publish — Release a new version of Atlas

with ❤️  Expo