@everframe/metro
withEverframe(config, { projectRoot, dev }) preserves the existing Metro
configuration and adds a synchronous identity polyfill for Android and iOS.
It generates a build ID and writes .everframe/<buildId>/manifest.partial.json
with an identity.js polyfill. The polyfill sets globalThis.__EVERFRAME_BUILD__
before application modules execute.
Each platform has its own ID and bundle name: index.android.bundle on Android,
main.jsbundle on iOS. Native version, release labels and OTA provider update IDs
must not replace this bundle identity. Set enabled: false when the corresponding
SDK is excluded from a build.
Use one isolated staging directory for each build job. Metro stages both platforms
at configuration time. Collection reads the generated identity from the composed
map, checks the staged partial and compiled build ID, and promotes that completed
build to latest-<platform>.json. A later configuration load before collection is
safe; do not run another Metro invocation between collection and upload. Retain matching bytecode and maps;
reusing a build ID with different generated bytes is not a new release.
After the Hermes compiler has emitted bytecode and its composed map:
npx @everframe/cli build collect --staging .everframe --platform android \
--bundle path/to/index.android.bundle \
--source-map path/to/index.android.bundle.map
npx @everframe/cli build verify --staging .everframe --platform android --release
npx @everframe/cli sourcemaps upload-hermes --manifest .everframe \
--platform android --app-id "$EVERFRAME_APP_ID"
Provide the scoped EVERFRAME_API_TOKEN only to the build/upload process. See the
Expo Updates guide for export and loaded-bundle identity.
Source commit provenance
Current React Native SDKs attach the loaded Hermes bundle identity to ordinary feedback reports as well as crashes. Release-health monitoring can be disabled; the report still resolves the exact uploaded bundle, including OTA updates sharing a native version/build.
React Native iOS/Android builds record an optional Git commit, branch, and dirty
status. Metro captures these before writing staging files; collection and upload
preserve that snapshot, including Expo exports and OTA updates. Keep .everframe/
in your Git ignore rules. A missing Git checkout does not stop builds or uploads.
Explicit withEverframe(config, { commit: '<full-sha>' }) takes precedence over
local HEAD, then CI fallback (GITHUB_SHA, CI_COMMIT_SHA, BITBUCKET_COMMIT,
BUILD_SOURCEVERSION). Use a full 40- or 64-character hexadecimal commit.
Detached checkouts omit the branch; unavailable status is unknown, not clean.
everframe sourcemaps upload-hermes, upload-expo-export, and native dsym,
elf, and r8 upload commands accept --commit <full-sha>. An override with a
different commit drops recorded branch/dirty facts. Legacy staged records without
provenance stay unknown; delayed staged uploads never read the uploader's HEAD.
Direct single-artifact uploads detect Git at invocation from the working directory,
so use --commit when uploading older files. Aggregate native dsym upload-build
and elf upload-build commands (including Xcode/Gradle integration) leave source
provenance unknown by default: their symbols may include reused or vendor binaries.
Use --commit only when every selected artifact belongs to that source commit;
otherwise upload each known artifact with its own explicit commit. Automatic
per-artifact native source attribution remains follow-up work.
The service must support the additive vcs manifest field before using these
tooling versions. Older clients remain supported by the updated service. Deploy
server support before publishing the new tooling; do not strip provenance in
response to an arbitrary upload failure.