@keepsnappy/react-native 0.1.0-alpha.19 → 0.1.0-alpha.20

package/README.md

@@ -33,18 +33,33 @@ Workers write atomic, content-addressed fragments under `.keepsnappy/components/
 
 `app.config.js` / `app.json`:
 
-```js
-plugins: [/* ... */, '@keepsnappy/react-native'],
+```json
+"plugins": [["@keepsnappy/react-native", { "measureFromLaunch": true, "renderTimes": true }]]
 ```
 
-Native code needs no further setup: Expo autolinking links the module from `expo-module.config.json` (iOS pod `KeepSnappy`, Android `expo.modules.keepsnappy.KeepSnappyModule`) when the flag is on. Set `EXPO_PUBLIC_KEEPSNAPPY` the same way for `expo prebuild` (or the EAS build) and for the JS bundle, then `pod install` / rebuild.
+The build switch is `KEEPSNAPPY=1` in the build environment (EAS build profile `env`, CI). Without it the build carries no SDK, whatever the options say. Native code needs no further setup: Expo autolinking links the module from `expo-module.config.json` (iOS pod `KeepSnappy`, Android `expo.modules.keepsnappy.KeepSnappyModule`) when the switch is on. Set `KEEPSNAPPY` the same way for `expo prebuild` (or the EAS build) and for the JS bundle, then `pod install` / rebuild.
+
+### Plugin options
+
+`build-config.js` resolves them for the config plugin and for Metro (which reads them from the app config), so prebuild and the bundle agree.
+
+| Option | Default | Meaning | Stands for |
+|---|---|---|---|
+| `measureFromLaunch` | `true` | Measures from the first frame. `false`: markers only until a settings link turns collection on. | `EXPO_PUBLIC_KEEPSNAPPY_AUTO=1` |
+| `renderTimes` | `true` | Records React render times per component, with React's profiling renderer. | `EXPO_PUBLIC_KEEPSNAPPY_PROFILE=1` + `KEEPSNAPPY_REACT_PROFILING=1`; with `waitForActivation`: `KEEPSNAPPY_REACT_PROFILING=switch` |
+| `waitForActivation` | `false` | Dormant: nothing runs until a KeepSnappy activation link, from the next launch on. For one build that serves other e2e jobs too. Wins over `measureFromLaunch`. | `EXPO_PUBLIC_KEEPSNAPPY_MODE=dormant` |
+| `tapText` | `true` | `false`: never reads text on screen to name a tap. | `EXPO_PUBLIC_KEEPSNAPPY_TAP_TEXT=0` |
+
+Unknown options and non-boolean values fail prebuild and Metro. The key is never an option: it stays a CI secret (`KEEPSNAPPY_KEY`). Builds that push their own data (BrowserStack, Android) read `EXPO_PUBLIC_KEEPSNAPPY_KEY` and `EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL` from the build environment.
+
+The older variables keep working. A variable set (non-empty) in the environment wins over its option. A build switched on only by `EXPO_PUBLIC_KEEPSNAPPY=1` leaves unset options off, so it builds exactly as before the options existed (`test/build-inputs.test.ts` pins this against alpha.19).
 
 ### What the config plugin does
 
-It decides whether the native module is linked, from `EXPO_PUBLIC_KEEPSNAPPY` at prebuild time:
+It decides whether the native module is linked, from the build switch (`KEEPSNAPPY` or `EXPO_PUBLIC_KEEPSNAPPY`) at prebuild time:
 
 - **Flag off:** the package is excluded from Expo autolinking. iOS: the Podfile's `use_expo_modules!` becomes `use_expo_modules!({ exclude: ['<package>'] })` (this also reaches the `expo-configure-project.sh` build phase that regenerates `ExpoModulesProvider.swift`). Android: `expoAutolinking.exclude` is set in `settings.gradle` before `expoAutolinking.useExpoModules()`. `expo-modules-autolinking` 57 reads exclusions only from the app's `package.json` and from these call sites. Result: no `KeepSnappy` pod, no Android project, no provider entry.
-- **Flag on:** the exclusion is removed again (prebuild without `--clean` edits existing files) and `extra.keepsnappy = { native: true, profilingRenderer }` is added to the app config, so flag-on and flag-off builds have different native fingerprints. `profilingRenderer` is `always` (`KEEPSNAPPY_REACT_PROFILING=1`), `switch` (`=switch`) or `off`, read at prebuild time, so the three builds fingerprint differently too. Set `KEEPSNAPPY_REACT_PROFILING` the same way for prebuild and for the bundle.
+- **Flag on:** the exclusion is removed again (prebuild without `--clean` edits existing files) and `extra.keepsnappy = { native: true, profilingRenderer }` is added to the app config, so flag-on and flag-off builds have different native fingerprints. `profilingRenderer` is `always` (`KEEPSNAPPY_REACT_PROFILING=1`), `switch` (`=switch`) or `off`, resolved at prebuild time from the variable or the `renderTimes` option, so the three builds fingerprint differently too. Set `KEEPSNAPPY_REACT_PROFILING` the same way for prebuild and for the bundle.
 
 A Podfile whose `use_expo_modules!` already takes arguments (or a settings.gradle without `expoAutolinking.useExpoModules()`) cannot be edited safely; with the flag off, prebuild then fails with a message saying what to add. No Info.plist, entitlement or manifest change is needed: the module only uses `os_signpost`/`OSLog`, `android.os.Trace`, logcat and the app's own files directory.
 
@@ -53,18 +68,19 @@ A Podfile whose `use_expo_modules!` already takes arguments (or a settings.gradl
 1. Appends `js/hook.polyfill.js` to `serializer.getPolyfills`, so a `__REACT_DEVTOOLS_GLOBAL_HOOK__` exists before React evaluates (it chains onto an existing hook instead of replacing it; in dev it defers to React DevTools). In a dormant build it first reads the activation and installs nothing when not activated.
 2. Sets `transformer.babelTransformerPath` to `js/babel-transformer.js`, which delegates to the app's transformer and
    - prepends `import "<relative path>/js/sdk/boot";` to the entry file (`package.json` `main`), which puts the SDK into the graph;
-   - inlines `process.env.EXPO_PUBLIC_*` in the SDK's own files with the build-time values. `babel-preset-expo` does not inline `EXPO_PUBLIC_*` inside `node_modules`, so without this step the SDK would read `undefined` at runtime.
+   - inlines `process.env.EXPO_PUBLIC_*` in the SDK's own files with the build-time values: the `EXPO_PUBLIC_KEEPSNAPPY*` values resolved from the options and the environment (`KEEPSNAPPY_BUILD_VARS`), other names from the environment. `babel-preset-expo` does not inline `EXPO_PUBLIC_*` inside `node_modules`, so without this step the SDK would read `undefined` at runtime.
 3. Appends the boot module to `serializer.getModulesRunBeforeMainModule` (ignored by Expo's serializer, harmless: the boot import is the entry's first statement; kept for plain Metro).
 
 The upstream transformer path, entry file and boot file reach Metro's transform workers through `KEEPSNAPPY_UPSTREAM_BABEL_TRANSFORMER`, `KEEPSNAPPY_ENTRY_FILE` and `KEEPSNAPPY_BOOT_FILE` (internal, set by `withKeepSnappy`).
 
 ## Environment / config contract
 
-All values are read at **bundle time** (Expo CLI loads `.env*` into the Metro process). Change them, then rebuild the JS bundle with a clean cache (`--reset-cache` / `expo start -c`).
+All values are read at **bundle time** (Expo CLI loads `.env*` into the Metro process). Change them, then rebuild the JS bundle with a clean cache (`--reset-cache` / `expo start -c`). The plugin options above stand for some of them; a variable set here wins over its option.
 
 | Variable (current name) | Proposed public name | Values | Effect |
 |---|---|---|---|
-| `EXPO_PUBLIC_KEEPSNAPPY` | `KEEPSNAPPY` | `1` = on, anything else = off | Build flag. Off: Metro config untouched, SDK not in the bundle. On: hook polyfill + SDK boot in the bundle. |
+| `KEEPSNAPPY` | | `1` = on | The build switch. With it, unset plugin options take their defaults. |
+| `EXPO_PUBLIC_KEEPSNAPPY` | `KEEPSNAPPY` | `1` = on, anything else = off | Build flag (older form of the switch). Off (and no `KEEPSNAPPY=1`): Metro config untouched, SDK not in the bundle. On: hook polyfill + SDK boot in the bundle. |
 | `EXPO_PUBLIC_KEEPSNAPPY_MODE` | `KEEPSNAPPY_MODE` | `dormant` / `auto` | `auto`: measure from the first frame (same as `KEEPSNAPPY_AUTO=1`). `dormant`: nothing runs until activated (below); once activated the process measures like `auto`. Unset: `auto` if `KEEPSNAPPY_AUTO=1`, else manual (markers until a settings link turns collection on). |
 | `EXPO_PUBLIC_KEEPSNAPPY_AUTO` | `KEEPSNAPPY_AUTO` | `1` = on | Measure-only builds: collection (React hook walk, PerformanceObserver, log to console and native file) is on from the first frame, with no deep link needed. Off: only markers until a settings link turns collection on. Equivalent to `KEEPSNAPPY_MODE=auto`; `KEEPSNAPPY_MODE` wins when both are set. |
 | `EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL` | `KEEPSNAPPY_INGEST_URL` | URL of the farm ingest (`POST /v1/ingest`) | Push client. Push is on only if both the URL and the key are set. |
@@ -77,7 +93,7 @@ All values are read at **bundle time** (Expo CLI loads `.env*` into the Metro pr
 | `EXPO_PUBLIC_KEEPSNAPPY_CPUPROF`, `..._CPUPROF_HZ` | `KEEPSNAPPY_CPUPROF` | `1` = on; Hz (default 250) | Default of `cpuprof`/`cpuhz`: Hermes sampling profiler (iOS), `Documents/keepsnappy/cpu-<process>-<span>.cpuprofile`. Inside a run it samples from the first window to `flush=1` and stops and dumps there, so the synchronous dump never lands in a measured window; otherwise one file per span of overlapping windows, dumped when the last one ends. `<process>` is the launch's `processId` (startup line), so launches never overwrite each other. |
 | `KEEPSNAPPY_REACT_PROFILING` (Metro process; also read by the config plugin) | | `1` / `switch` / unset | `1`: `withKeepSnappy` resolves RN's production renderer to `ReactFabric-profiling` (fiber durations, updaters), flag or not; for dedicated perf builds (docs/plans/37). `switch` (flag on only, ignored with the flag off): both Fabric renderers go into the bundle and each process loads one at launch (below). Unset: production renderer only. |
 
-Only the names above are read today. The proposed names drop the `EXPO_PUBLIC_` prefix because the values never need to be readable by app code: the transformer inlines them into the SDK only, so a non-prefixed `KEEPSNAPPY=1` would also keep the flag out of the app's own `process.env` surface and match the CLI / CI wording (`KEEPSNAPPY=1` in doc 23). Migration plan: accept both names (new name wins), then drop the old ones.
+Only the names above are read today; of the proposed names only `KEEPSNAPPY` exists (alpha.20), the rest are plugin options now. The proposed names drop the `EXPO_PUBLIC_` prefix because the values never need to be readable by app code: the transformer inlines them into the SDK only, so a non-prefixed `KEEPSNAPPY=1` would also keep the flag out of the app's own `process.env` surface and match the CLI / CI wording (`KEEPSNAPPY=1` in doc 23). Migration plan: accept both names (new name wins), then drop the old ones.
 
 ### Renderer switch (`KEEPSNAPPY_REACT_PROFILING=switch`)
 

package/app.plugin.js

@@ -1,29 +1,32 @@
 // Expo config plugin for the KeepSnappy SDK.
 //
 // The native module (iOS pod KeepSnappy, Android expo.modules.keepsnappy) is linked
-// by Expo autolinking from expo-module.config.json. With the build flag off
-// (EXPO_PUBLIC_KEEPSNAPPY is not "1" when `expo prebuild` runs) this plugin
-// excludes the package from Expo autolinking, so a store build carries no SDK
-// native code: no pod, no Android project, no ExpoModulesProvider entry. With
-// the flag on it removes that exclusion again (prebuild without --clean edits
-// the existing files) and records the flag in the app config, so the native
-// fingerprints of flag-on and flag-off builds differ. It also records which
-// React renderer the bundle carries (KEEPSNAPPY_REACT_PROFILING, see metro.js):
-// `always` (=1), `switch` (=switch) or `off`.
+// by Expo autolinking from expo-module.config.json. With the build switch off
+// (neither KEEPSNAPPY nor the older EXPO_PUBLIC_KEEPSNAPPY is "1" when
+// `expo prebuild` runs) this plugin excludes the package from Expo autolinking,
+// so a store build carries no SDK native code: no pod, no Android project, no
+// ExpoModulesProvider entry. With the switch on it removes that exclusion again
+// (prebuild without --clean edits the existing files) and records the switch in
+// the app config, so the native fingerprints of on and off builds differ. It
+// also records which React renderer the bundle carries (KEEPSNAPPY_REACT_PROFILING
+// or the renderTimes option, see build-config.js and metro.js): `always` (=1),
+// `switch` (=switch) or `off`.
+//
+// The plugin options (measureFromLaunch, renderTimes, waitForActivation, tapText)
+// are resolved in build-config.js; Metro reads the same options from the app config.
 //
 // expo-modules-autolinking reads exclusions only from the app's package.json and
 // from command arguments, so the Podfile's `use_expo_modules!` call and
 // settings.gradle's `expoAutolinking` extension are where the exclusion goes.
 
 const { withPodfile, withSettingsGradle } = require('expo/config-plugins');
+const { PACKAGE_NAMES, resolveBuild } = require('./build-config');
 
 const PACKAGE_NAME = require('./package.json').name;
-const PACKAGE_NAMES = [...new Set([PACKAGE_NAME, '@keepsnappy/react-native'])];
 const namesFor = name => name === PACKAGE_NAME ? PACKAGE_NAMES : [name];
+// Written into every store build's Podfile and settings.gradle, so into its fingerprint: keep the text as it is.
 const TAG = 'keepsnappy: native module excluded, EXPO_PUBLIC_KEEPSNAPPY is not 1';
 
-const isEnabled = () => (process.env.EXPO_PUBLIC_KEEPSNAPPY) === '1';
-
 const profilingRenderer = (value = (process.env.KEEPSNAPPY_REACT_PROFILING)) => {
   if (value === '1') {
     return 'always';
@@ -44,7 +47,7 @@ const editPodfile = (contents, enabled, name = PACKAGE_NAME) => {
     }
     throw new Error(
       `${name}: cannot exclude the native module, the Podfile has no plain \`use_expo_modules!\` call. ` +
-        `Add exclude: [${quoted(name)}] to it yourself, or set EXPO_PUBLIC_KEEPSNAPPY=1.`,
+        `Add exclude: [${quoted(name)}] to it yourself, or set KEEPSNAPPY=1.`,
     );
   }
   const indent = match[1];
@@ -70,19 +73,19 @@ const editSettingsGradle = (contents, enabled, language = 'groovy', name = PACKA
   if (at < 0) {
     throw new Error(
       `${name}: cannot exclude the native module, settings.gradle has no \`expoAutolinking.useExpoModules()\` call. ` +
-        'Set expoAutolinking.exclude yourself, or set EXPO_PUBLIC_KEEPSNAPPY=1.',
+        'Set expoAutolinking.exclude yourself, or set KEEPSNAPPY=1.',
     );
   }
   lines.splice(at, 0, gradleLine(language, name));
   return lines.join('\n');
 };
 
-const withKeepSnappy = config => {
-  const enabled = isEnabled();
+const withKeepSnappy = (config, options) => {
+  const { enabled, vars } = resolveBuild(options);
   if (enabled) {
     config.extra = {
       ...config.extra,
-      keepsnappy: { native: true, profilingRenderer: profilingRenderer() },
+      keepsnappy: { native: true, profilingRenderer: profilingRenderer(vars.KEEPSNAPPY_REACT_PROFILING ?? '') },
     };
   }
   config = withPodfile(config, mod => {

package/build-config.js

@@ -0,0 +1,99 @@
+// The KeepSnappy build settings, resolved once for the config plugin (app.plugin.js) and Metro (metro.js), so prebuild and
+// the bundle agree.
+//
+// The build switch is KEEPSNAPPY=1 in the build environment (EAS profile env, CI). The older EXPO_PUBLIC_KEEPSNAPPY=1
+// still turns the SDK on. Without either, the build carries no SDK: the plugin options are not read.
+//
+// What a build measures comes from the plugin options in app.json, `["@keepsnappy/react-native", { ... }]`. Each option
+// stands for older variables, and a variable set (non-empty) in the environment wins over the option:
+//   measureFromLaunch  EXPO_PUBLIC_KEEPSNAPPY_AUTO=1           (with EXPO_PUBLIC_KEEPSNAPPY_MODE, one setting)
+//   waitForActivation  EXPO_PUBLIC_KEEPSNAPPY_MODE=dormant     (same setting; wins over measureFromLaunch)
+//   renderTimes        EXPO_PUBLIC_KEEPSNAPPY_PROFILE=1, KEEPSNAPPY_REACT_PROFILING=1
+//                      (waiting for activation: KEEPSNAPPY_REACT_PROFILING=switch, the activation asks for render times)
+//   tapText            EXPO_PUBLIC_KEEPSNAPPY_TAP_TEXT=0 when false
+// Options left out take DEFAULTS under KEEPSNAPPY=1. A build switched on only by EXPO_PUBLIC_KEEPSNAPPY=1 leaves them
+// out, so it builds exactly as before the options existed.
+//
+// The key is never an option: it stays a CI secret. Builds that push their own data (BrowserStack, Android) read
+// EXPO_PUBLIC_KEEPSNAPPY_KEY and EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL from the build environment.
+
+const PACKAGE_NAME = require('./package.json').name;
+const PACKAGE_NAMES = [...new Set([PACKAGE_NAME, '@keepsnappy/react-native'])];
+
+const DEFAULTS = { measureFromLaunch: true, renderTimes: true, waitForActivation: false, tapText: true };
+const UNSET = { measureFromLaunch: false, renderTimes: false, waitForActivation: false, tapText: true };
+
+const isSet = value => value !== undefined && value !== '';
+
+const isEnabled = () => process.env.KEEPSNAPPY === '1' || process.env.EXPO_PUBLIC_KEEPSNAPPY === '1';
+
+function checkOptions(options, name = PACKAGE_NAME) {
+  if (options === undefined || options === null) {
+    return {};
+  }
+  if (typeof options !== 'object' || Array.isArray(options)) {
+    throw new Error(`${name}: the plugin options must be an object, such as { "measureFromLaunch": true }`);
+  }
+  for (const [key, value] of Object.entries(options)) {
+    if (!(key in DEFAULTS)) {
+      throw new Error(
+        `${name}: unknown option "${key}"; the options are ${Object.keys(DEFAULTS).join(', ')}.` +
+          (/key|token|secret|ingest|url/i.test(key)
+            ? ' The key never goes in app.json: it stays a CI secret (KEEPSNAPPY_KEY); builds for BrowserStack or Android read EXPO_PUBLIC_KEEPSNAPPY_KEY and EXPO_PUBLIC_KEEPSNAPPY_INGEST_URL from the build environment.'
+            : ''),
+      );
+    }
+    if (typeof value !== 'boolean') {
+      throw new Error(`${name}: ${key} must be true or false, not ${JSON.stringify(value)}`);
+    }
+  }
+  return options;
+}
+
+// The values the SDK reads: every EXPO_PUBLIC_KEEPSNAPPY* variable of the environment and KEEPSNAPPY_REACT_PROFILING,
+// plus the ones the options stand for.
+function resolveBuild(rawOptions) {
+  const options = checkOptions(rawOptions);
+  const vars = Object.fromEntries(
+    Object.entries(process.env).filter(([name]) => name.startsWith('EXPO_PUBLIC_KEEPSNAPPY') || name === 'KEEPSNAPPY_REACT_PROFILING'),
+  );
+  if (!isEnabled()) {
+    return { enabled: false, vars };
+  }
+  const unset = process.env.KEEPSNAPPY === '1' ? DEFAULTS : UNSET;
+  const option = key => options[key] ?? unset[key];
+  vars.EXPO_PUBLIC_KEEPSNAPPY = '1';
+  if (!isSet(process.env.EXPO_PUBLIC_KEEPSNAPPY_MODE) && !isSet(process.env.EXPO_PUBLIC_KEEPSNAPPY_AUTO)) {
+    if (option('waitForActivation')) {
+      vars.EXPO_PUBLIC_KEEPSNAPPY_MODE = 'dormant';
+    } else if (option('measureFromLaunch')) {
+      vars.EXPO_PUBLIC_KEEPSNAPPY_AUTO = '1';
+    }
+  }
+  const dormant = vars.EXPO_PUBLIC_KEEPSNAPPY_MODE === 'dormant';
+  if (option('renderTimes')) {
+    if (!isSet(process.env.KEEPSNAPPY_REACT_PROFILING)) {
+      vars.KEEPSNAPPY_REACT_PROFILING = dormant ? 'switch' : '1';
+    }
+    if (!dormant && !isSet(process.env.EXPO_PUBLIC_KEEPSNAPPY_PROFILE)) {
+      vars.EXPO_PUBLIC_KEEPSNAPPY_PROFILE = '1';
+    }
+  }
+  if (!option('tapText') && !isSet(process.env.EXPO_PUBLIC_KEEPSNAPPY_TAP_TEXT)) {
+    vars.EXPO_PUBLIC_KEEPSNAPPY_TAP_TEXT = '0';
+  }
+  return { enabled: true, vars };
+}
+
+// The options of the plugin entry in the app's Expo config (app.json, app.config.js or app.config.ts), as prebuild
+// passes them to the plugin. Metro reads them here because it does not run config plugins.
+function appPluginOptions(projectRoot) {
+  const { getConfig } = require('expo/config');
+  const { exp } = getConfig(projectRoot, { skipSDKVersionRequirement: true });
+  // A path into the package (`@keepsnappy/react-native/app.plugin`) is the same plugin.
+  const isOurs = name => typeof name === 'string' && PACKAGE_NAMES.some(p => name === p || name.startsWith(`${p}/`));
+  const entry = (exp.plugins ?? []).find(plugin => isOurs(Array.isArray(plugin) ? plugin[0] : plugin));
+  return Array.isArray(entry) ? entry[1] : undefined;
+}
+
+module.exports = { DEFAULTS, PACKAGE_NAMES, isEnabled, checkOptions, resolveBuild, appPluginOptions };

package/js/babel-transformer.js

@@ -4,9 +4,12 @@
 //
 // babel-preset-expo inlines EXPO_PUBLIC_* only outside node_modules, and the
 // SDK is installed into node_modules, so this wrapper inlines the SDK's own
-// EXPO_PUBLIC_* reads with the build-time values.
+// EXPO_PUBLIC_* reads with the build-time values: the EXPO_PUBLIC_KEEPSNAPPY*
+// values withKeepSnappy resolved from the plugin options and the environment
+// (KEEPSNAPPY_BUILD_VARS, see build-config.js), any other name from the environment.
 
 const path = require('path');
+const { isEnabled } = require('../build-config');
 
 const upstreamPath = (process.env.KEEPSNAPPY_UPSTREAM_BABEL_TRANSFORMER);
 const entryFile = (process.env.KEEPSNAPPY_ENTRY_FILE);
@@ -15,8 +18,9 @@ const sdkVersion = process.env.KEEPSNAPPY_SDK_VERSION;
 const clientPackages = JSON.parse(process.env.KEEPSNAPPY_CLIENT_PACKAGES ?? '[]');
 const projectRoot = process.env.KEEPSNAPPY_PROJECT_ROOT;
 const componentCacheKey = process.env.KEEPSNAPPY_COMPONENT_CACHE_KEY ?? '';
+const buildVars = process.env.KEEPSNAPPY_BUILD_VARS ? JSON.parse(process.env.KEEPSNAPPY_BUILD_VARS) : null;
 
-if (!upstreamPath || !entryFile || !bootFile || !sdkVersion) {
+if (!upstreamPath || !entryFile || !bootFile || !sdkVersion || !buildVars) {
   throw new Error(
     'KeepSnappy Babel transformer loaded without withKeepSnappy env (KEEPSNAPPY_*)',
   );
@@ -27,16 +31,19 @@ const upstream = require(upstreamPath);
 const packageRoot = path.resolve(__dirname, '..') + path.sep;
 const ENV_REF = /\bprocess\.env\.(EXPO_PUBLIC_[A-Z0-9_]+)\b/g;
 
+const buildValue = name =>
+  name.startsWith('EXPO_PUBLIC_KEEPSNAPPY') ? buildVars[name] : process.env[name];
+
 const inlineEnv = src =>
   src.replace(ENV_REF, (_match, name) =>
-    process.env[name] === undefined ? 'undefined' : JSON.stringify(process.env[name]),
+    buildValue(name) === undefined ? 'undefined' : JSON.stringify(buildValue(name)),
   );
 
 const envSignature = () =>
-  Object.keys(process.env)
+  Object.keys(buildVars)
     .filter(name => name.startsWith('EXPO_PUBLIC_KEEPSNAPPY'))
     .sort()
-    .map(name => `${name}=${process.env[name]}`)
+    .map(name => `${name}=${buildVars[name]}`)
     .join('&');
 
 const bootImport = () => {
@@ -56,7 +63,7 @@ const absolute = (filename, options) =>
 module.exports = {
   ...upstream,
   transform(args) {
-    if (process.env.EXPO_PUBLIC_KEEPSNAPPY !== '1') return upstream.transform(args);
+    if (!isEnabled()) return upstream.transform(args);
     const file = absolute(args.filename, args.options);
     const original = args;
     if (file === entryFile) {

package/metro.js

@@ -1,6 +1,13 @@
 // withKeepSnappy(metroConfig): the only line an app adds to metro.config.js.
 //
-// With EXPO_PUBLIC_KEEPSNAPPY=1 it
+// The build settings come from build-config.js: the switch KEEPSNAPPY=1 (or the
+// older EXPO_PUBLIC_KEEPSNAPPY=1), the plugin options in the app config and the
+// older variables, which win over the options. Below, "the flag" is that switch
+// and KEEPSNAPPY_REACT_PROFILING is the resolved value (the renderTimes option or
+// the variable). The resolved EXPO_PUBLIC_KEEPSNAPPY_* values reach the SDK
+// transformer as KEEPSNAPPY_BUILD_VARS.
+//
+// With the flag on it
 //  1. appends the React DevTools hook as a Metro polyfill, so the hook exists
 //     before any module (React included) evaluates;
 //  2. wraps the Babel transformer so the app's entry module imports the SDK boot
@@ -11,9 +18,9 @@
 //     zustand store's setState through the cause tracker (REQ-MEAS-32 timers).
 // Without the flag it returns the config object untouched.
 //
-// KEEPSNAPPY_REACT_PROFILING=1 (independent of the flag) resolves React Native's
-// production renderer to its profiling build (fiber actualDuration /
-// selfBaseDuration, root.memoizedUpdaters), the same rewrite as
+// KEEPSNAPPY_REACT_PROFILING=1 (the variable alone also with the flag off)
+// resolves React Native's production renderer to its profiling build (fiber
+// actualDuration / selfBaseDuration, root.memoizedUpdaters), the same rewrite as
 // @callstack/inspector's withInspector. Nothing else in the bundle changes.
 //
 // KEEPSNAPPY_REACT_PROFILING=switch (flag on only) bundles both Fabric renderers
@@ -22,6 +29,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { appPluginOptions, isEnabled, resolveBuild } = require('./build-config');
 
 const POLYFILL_PATH = path.join(__dirname, 'js', 'hook.polyfill.js');
 const BOOT_PATH = path.join(__dirname, 'js', 'sdk', 'boot.ts');
@@ -30,10 +38,7 @@ const TRANSFORMER_PATH = path.join(__dirname, 'js', 'babel-transformer.js');
 const ENV_UPSTREAM = 'KEEPSNAPPY_UPSTREAM_BABEL_TRANSFORMER';
 const ENV_ENTRY = 'KEEPSNAPPY_ENTRY_FILE';
 const ENV_BOOT = 'KEEPSNAPPY_BOOT_FILE';
-
-const isEnabled = () => (process.env.EXPO_PUBLIC_KEEPSNAPPY) === '1';
-const isProfiling = () => (process.env.KEEPSNAPPY_REACT_PROFILING) === '1';
-const isSwitch = () => (process.env.KEEPSNAPPY_REACT_PROFILING) === 'switch';
+const ENV_VARS = 'KEEPSNAPPY_BUILD_VARS';
 
 const SWITCH_PATH = path.join(__dirname, 'js', 'renderer-switch.js');
 // The names renderer-switch.js requires; they resolve next to RN's shim.
@@ -187,16 +192,17 @@ const resolveEntry = projectRoot => {
 
 function withKeepSnappy(input, { clientPackages = [] } = {}) {
   if (!isEnabled()) {
-    return isProfiling() ? withReactProfiling(input) : input;
+    return process.env.KEEPSNAPPY_REACT_PROFILING === '1' ? withReactProfiling(input) : input;
   }
+  const projectRoot = input.projectRoot ?? process.cwd();
+  const { vars } = resolveBuild(appPluginOptions(projectRoot));
   let config = input;
-  if (isProfiling()) {
+  if (vars.KEEPSNAPPY_REACT_PROFILING === '1') {
     config = withReactProfiling(input);
-  } else if (isSwitch()) {
+  } else if (vars.KEEPSNAPPY_REACT_PROFILING === 'switch') {
     config = withRendererSwitch(input);
   }
   config = withStoreWrap(config);
-  const projectRoot = config.projectRoot ?? process.cwd();
   const entry = resolveEntry(projectRoot);
   const upstream = config.transformer?.babelTransformerPath;
   if (!entry || !upstream) {
@@ -211,6 +217,7 @@ function withKeepSnappy(input, { clientPackages = [] } = {}) {
   process.env[ENV_UPSTREAM] = upstream;
   process.env[ENV_ENTRY] = entry;
   process.env[ENV_BOOT] = BOOT_PATH;
+  process.env[ENV_VARS] = JSON.stringify(vars);
   const packages = [...new Set(clientPackages)].sort();
   process.env.KEEPSNAPPY_CLIENT_PACKAGES = JSON.stringify(packages);
   process.env.KEEPSNAPPY_PROJECT_ROOT = projectRoot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keepsnappy/react-native",
-  "version": "0.1.0-alpha.19",
+  "version": "0.1.0-alpha.20",
   "description": "KeepSnappy in-app SDK for React Native / Expo: zero-code measurement windows, React commit hook, native signposts and log file",
   "license": "UNLICENSED",
   "repository": {
@@ -13,6 +13,7 @@
   },
   "files": [
     "app.plugin.js",
+    "build-config.js",
     "metro.js",
     "expo-module.config.json",
     "js",