README.md

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