Skip to content

feat: Add Atlas Stats Output File#90

Open
jasongaare wants to merge 7 commits intoexpo:mainfrom
jasongaare:feature/atlas-stats
Open

feat: Add Atlas Stats Output File#90
jasongaare wants to merge 7 commits intoexpo:mainfrom
jasongaare:feature/atlas-stats

Conversation

@jasongaare
Copy link

Summary

Exports a lightweight .expo/atlas-stats.json file when running expo export with Atlas enabled. This file is optimized for CI/CD environments seeking to provide simply bundle size analysis without the full module graph.

Also implements a "stats-only" mode that skips writing the large atlas.jsonl when it isn't needed (i.e. in a CI/CD environment).

Stats file format

  [
    {
      "platform": "ios",
      "environment": "client",
      "entryPoint": "/path/to/app/index.js",
      "bundleSize": 2458624,
      "packages": {
        "react": 85234,
        "react-native": 456789,
        "expo": 123456,
        "@company/ui-lib": 234567
      },
      "files": {
        "app/components/Button.tsx": 2345,
        "app/screens/HomeScreen.tsx": 5678,
        "app/utils/helpers.ts": 1234
      },
      "assets": {
        "assets/images/logo.png": 12345,
        "assets/fonts/custom.ttf": 23456
      }
    }
  ]

Stats-only mode

  • Add statsOnly option to withExpoAtlas() config
  • Add EXPO_ATLAS_STATS_ONLY environment variable support
  • Skip atlas.jsonl creation when stats-only mode is enabled

Usage for stats-only mode

// Via config option                                                     
module.exports = withExpoAtlas(config, { statsOnly: true })              
                                                                         
// Via environment variable                                              
EXPO_ATLAS=1 EXPO_ATLAS_STATS_ONLY=true npx expo export                               

jasongaare and others added 7 commits January 21, 2026 12:23
Generate a lightweight `.expo/atlas-stats.json` file automatically whenever
`atlas.jsonl` is created during Metro bundling. This stats file contains
package-level size aggregations optimized for CI/CD workflows and git diffs.

Key features:
- Automatic generation during Metro export (no extra flags needed)
- Package-level size totals aggregated from all modules
- Bundle metadata (platform, environment, entryPoint, bundleSize)
- Pretty-printed JSON with sorted keys for diff-friendly output
- <100KB file size (vs 80+ MB full atlas.jsonl)
- In-memory accumulation with single write at end of export

Implementation:
- Add convertBundleToStats() to aggregate module sizes by package
- Add writeAtlasStatsEntry() to accumulate stats in memory
- Add finalizeAtlasStats() to write stats file after all bundles processed
- Export TypeScript types for AtlasStatsBundle and AtlasStatsFile
- Add comprehensive test coverage for stats generation

This enables teams to track bundle size changes in CI without parsing
the full atlas.jsonl file.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
  analysis

- Add EXPO_ATLAS_STATS_ONLY env var to skip atlas.jsonl generation
  - Break down stats into packages, files, and assets sections
  - Add auto-finalization on process exit for stats.json
  - Reduce disk I/O by ~92MB per export in stats-only mode
   Modified ensureAtlasFileExist to accept statsOnly parameter and create
   the directory without creating atlas.jsonl file. This fixes ENOENT errors
   when finalizing stats in CI environments where .expo directory doesn't exist.

   - Add statsOnly parameter to ensureAtlasFileExist function
   - Always call ensureAtlasFileExist in metro.ts, passing statsOnly flag
   - In stats-only mode, only create directory without atlas.jsonl validation
  - Extract ensureExpoDirExists to handle .expo directory creation
  independently
  - Simplify ensureAtlasFileExist to only handle atlas.jsonl
  validation/creation
  - Fix tests to expect app code in files instead of packages.app
  - Remove 4 redundant test cases
  - Remove disk I/O metrics from documentation comments
@jasongaare
Copy link
Author

jasongaare commented Jan 23, 2026

@byCedric not sure how much active development is going on with Atlas these days, but I've been using it to write a bundle-change analysis tool for our repo. the output essentially looks like this:

Screenshot 2026-01-23 at 9 13 53 AM

I was having trouble parsing the very large atlas.jsonl file, hence the addition of the simple atlas-stats.json file in this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant