# 1k Cold Start Ssr > Jotai Cold Start SSR + unified startup timing schema — cold start optimization via MMKV snapshot hydration and the cross-platform `[StartupTiming]` log taxonomy for OneKey native app. Use when debugging startup performance regressions, analyzing cold start timeline, comparing iOS vs Android startup phases, or modifying the snapshot hydration pipeline. Triggers on: cold start, startup optimization, 启动时间, SSR hydration, Balance displayed regression, MMKV snapshot, contextAtomBase, flushColdStartCache, __ONEKEY_CTX_ATOM_SNAPSHOT__, StartupTiming, main_host.did_start, bg_runner.start, ios.main_entry.evaluated, android.app.on_create, android.activity.on_create. - Skill: `onekeyhq/1k-cold-start-ssr` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add onekeyhq/1k-cold-start-ssr` - Raw SKILL.md: https://api.skillmd.com/api/skills/onekeyhq/1k-cold-start-ssr/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: onekeyhq (https://skillmd.com/u/onekeyhq) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/onekeyhq/1k-cold-start-ssr --- # Jotai Cold Start SSR Cold start optimization pattern for OneKey native app. Analogous to web SSR hydration — previous session's atom values are persisted to MMKV, pre-read at startup, and used as initial atom values so the first React render displays cached data immediately without waiting for network. **Currently supported:** Native (iOS/Android) only. Desktop/Web/Extension support planned. ## Architecture Overview ``` Session N (runtime) Session N+1 (cold start) ───────────────────── ────────────────────────── Phase 3: SAVE Phase 1: PRE-READ atom value changes index.ts (entry point) → coldStartValuesMap → MMKV.getString(snapshot) → debounce 2s → globalThis.__ONEKEY_CTX_ATOM_SNAPSHOT__ → flushColdStartCache() → MMKV.set(snapshot JSON) Phase 2: HYDRATION contextAtomBase (module load) Also flushes on AppState → read __ONEKEY_CTX_ATOM_SNAPSHOT__ 'background' event → use as atom initialValue → first render shows cached data Phase 4: REVALIDATION BG thread fetches fresh data → atoms update in-place → UI re-renders with live data ``` ## The Three Phases (Code Locations) ### Phase 1: Snapshot Pre-read **File:** `apps/mobile/index.ts` (top of entry point, before any module imports) ```typescript // Reads cold start cache from dedicated MMKV instance into globalThis // MUST execute before any contextAtomBase module evaluates const _ctxRaw = coldStartCacheStorage.getString( EAppSyncStorageKeys.onekey_jotai_context_atoms_snapshot, ); if (_ctxRaw) { (globalThis as any).__ONEKEY_CTX_ATOM_SNAPSHOT__ = JSON.parse(_ctxRaw); } ``` **Key constraints:** - Must be synchronous (MMKV is sync) - Must run before any `require()` that triggers `contextAtomBase` - Stored in dedicated `coldStartCacheStorage` MMKV instance (separate from app settings) ### Phase 2: Hydration **File:** `packages/kit-bg/src/states/jotai/utils/index.ts` — `contextAtomBase()` ```typescript // At module-load time, read cached value from pre-loaded snapshot let resolvedInitialValue = initialValue; if (snapshotKey) { const ctxSnapshot = (globalThis as any).__ONEKEY_CTX_ATOM_SNAPSHOT__; if (ctxSnapshot && snapshotKey in ctxSnapshot) { const cached = ctxSnapshot[snapshotKey]; resolvedInitialValue = { ...initialValue, ...cached }; } } const atomBuilder = memoizee(() => atom(resolvedInitialValue)); ``` **Key constraints:** - Runs at module evaluation time (not in React lifecycle) - `memoizee` ensures atom is created once with the cached value - Only applies to context atoms with a `name` — globalAtoms use MMKV per-key directly **Also:** `hydrateContextColdStartCacheForProvider()` — called at provider mount time for scoped hydration (per-account data). ### Phase 3: Save (for next cold start) **File:** `packages/kit-bg/src/states/jotai/utils/index.ts` — `flushColdStartCache()` ```typescript // Read-modify-write: patch only dirty keys into existing snapshot // Preserves cached values for scopes not rendered this session const snapshot = raw ? JSON.parse(raw) : {}; for (const name of coldStartDirtyKeys) { snapshot[name] = coldStartValuesMap.get(name); } coldStartCacheStorage.set(key, JSON.stringify(snapshot)); ``` **Trigger points:** - `scheduleColdStartSave()` — debounced 2s timer after any atom value change - `AppState 'background'` event — flush immediately when app goes to background **Key constraints:** - Uses read-modify-write (not full overwrite) to preserve unrendered scopes - All callers are on main thread — no cross-thread race - `coldStartValuesMap` tracks all rendered atom values via `wrappedUse()` ### Snapshot Cleanup `__ONEKEY_CTX_ATOM_SNAPSHOT__` is cleaned up on `HomePageReady` event (first screen rendered), not on `setTimeout(0)`. This ensures split-bundle lazy-loaded modules can still hydrate from the snapshot. ## Split Bundle: main vs background Bundle Sizes The app uses a dual-runtime split bundle architecture. Bundle sizes directly impact cold start: ``` common.jsbundle ~8.8MB Shared polyfills, loaded by native at app launch main.jsbundle ~10.1MB UI thread entry, async-evaluated after ~100ms defer background.bundle ~20.7MB BG thread, loaded in parallel Hermes runtime + segment files variable Lazy-loaded on demand (vault impls, icons, etc.) ``` **Impact on cold start timeline:** - `common.jsbundle` (8.8MB): blocks native → JS handoff (~100ms) - `main.jsbundle` (10.1MB): async eval takes ~1300ms — **the single biggest bottleneck** (87% of total startup) - `background.bundle` (20.7MB): runs in parallel, apiProxy import ~700ms. Currently non-blocking but close to critical path (BG ready at +1261ms vs main eval at +1300ms) - Segment loads: icon segments ~25ms each, vault settings ~20ms each, loaded on-demand after first render **Rules of thumb:** - Any code added to `main.jsbundle` directly increases the 1300ms eval time - Move non-critical code to segments (lazy `import()`) to keep main bundle lean - `background.bundle` size is less critical since it runs in parallel, but if it gets slower than main eval it becomes a blocker - Use `apps/mobile/scripts/unionBuild.js` to analyze bundle composition ## contextAtom Cold Start Cache Keys (SSR Keys) Each context atom that participates in Cold Start SSR must declare a `coldStartCacheKey`. These keys are registered in a central const: **File:** `packages/shared/src/consts/jotaiConsts.ts` ```typescript export const CONTEXT_ATOM_COLD_START_CACHE_KEYS = { accountWorthAtom: 'ctx:accountWorthAtom', lastConfirmedOverviewBalanceAtom: 'ctx:lastConfirmedOverviewBalanceAtom', walletTopBannersAtom: 'ctx:walletTopBannersAtom', selectedAccountsAtom: 'ctx:selectedAccountsAtom', accountSelectorStorageReadyAtom: 'ctx:accountSelectorStorageReadyAtom', activeAccountsAtom: 'ctx:activeAccountsAtom', renderedTokenListCacheAtom: 'ctx:renderedTokenListCacheAtom', } as const; ``` **Usage in atom definition:** ```typescript // packages/kit/src/states/jotai/contexts/tokenList/atoms.ts const { atom: renderedTokenListCacheAtom } = contextAtom( defaultValue, { coldStartCache: true, coldStartCacheKey: CONTEXT_ATOM_COLD_START_CACHE_KEYS.renderedTokenListCacheAtom, }, ); ``` **Scoped key format in MMKV snapshot:** Context atoms are scoped by provider (e.g., different accounts). The snapshot stores scoped keys: ``` {scopeKey}::{coldStartCacheKey} ``` Example: `hd-1--0::ctx:renderedTokenListCacheAtom` - `scopeKey` comes from `store.__ONEKEY_JOTAI_COLD_START_SCOPE_KEY__` (set when creating the Jotai store for a provider) - `coldStartCacheKey` is the `ctx:xxx` string from the const above **Adding a new SSR-cached atom:** 1. Add key to `CONTEXT_ATOM_COLD_START_CACHE_KEYS` in `jotaiConsts.ts` 2. Pass `{ coldStartCache: true, coldStartCacheKey: CONTEXT_ATOM_COLD_START_CACHE_KEYS.yourKey }` to `contextAtom()` 3. The atom will automatically be tracked by `wrappedUse()` and saved by `flushColdStartCache()` 4. On next cold start, the cached value will be used as `initialValue` via Phase 2 hydration **Caution:** Only cache atoms whose data is safe to show stale (e.g., token list, balance). Don't cache atoms with security-sensitive or time-critical data. ## SWR Cache (usePromiseResult) Separate from Jotai Cold Start SSR but shares the same `coldStartCacheStorage` MMKV instance. **File:** `packages/shared/src/utils/swrCacheUtils.ts` **Purpose:** Cache results of `usePromiseResult` hooks so repeated renders / screen revisits don't re-fetch from network. ```typescript // In usePromiseResult: const swrCacheEntry = swrCacheUtils.getWithTimestamp(swrKey); const effectiveInitResult = swrCacheEntry !== undefined ? swrCacheEntry.data : options.initResult; ``` **Key characteristics:** - Stored in `coldStartCacheStorage` under key `onekey_swr_cache` (single JSON blob) - Max 80 entries with LRU eviction (oldest timestamp dropped first) - Debounced 2s flush + immediate flush on `AppState 'background'` - Key builders centralized in `swrKeys` (e.g., `swrKeys.allNetworksCompatible(...)`, `swrKeys.defiEnabled(networkId)`) - Survives app restart (same MMKV instance as cold start cache) **Relationship to Cold Start SSR:** - SWR cache handles **hook-level** data (network responses, computed results) - Cold Start SSR handles **atom-level** data (Jotai state) - Both persist to the same MMKV instance (`coldStartCacheStorage`) but under different keys - Both flush on `AppState 'background'` ## Key Differences: contextAtom vs globalAtom | | contextAtom (scoped) | globalAtom (singleton) | |---|---|---| | Examples | tokenListAtom, accountWorthAtom | settingsPersistAtom | | Cold start source | `__ONEKEY_CTX_ATOM_SNAPSHOT__` (Phase 1-2) | MMKV per-key direct read | | Storage | `coldStartCacheStorage` blob | `jotaiMMKV` per-key | | Write mechanism | `flushColdStartCache` debounced | `atomWithStorage` immediate | | Scope | Per-provider (account-specific) | Global singleton | ## Diagnosing Cold Start Regressions ### Step 1: Collect NativeLogger Timeline NativeLogger writes to `app-latest.log`: - **iOS (simulator):** `~/Library/Developer/CoreSimulator/Devices/*/Containers/Data/Application/*/Library/Caches/logs/app-latest.log` - **iOS (device):** Xcode → Window → Devices and Simulators → select device → OneKey → "Download Container" → inspect `AppData.xcappdata/AppData/Library/Caches/logs/app-latest.log` - **Android:** `adb shell run-as so.onekey.app.wallet cat files/logs/app-latest.log > app-latest.log` ```bash # iOS simulator: find latest log LOG=$(find ~/Library/Developer/CoreSimulator/Devices \ -path "*/Containers/Data/Application/*" \ -name "app-latest.log" 2>/dev/null | xargs ls -t | head -1) # Extract the startup timeline — the unified StartupTiming tag + a few # adjacent signals (BgTransport, initCritical, Balance displayed, snapshot). grep -E "StartupTiming|BgTransport.*(→|transport)|Balance displayed|\ OneKey started|initCritical|JotaiBgSync.*resolving|HomePageReady|\ MMKV context|BackgroundEntry" "$LOG" | tail -60 ``` ### Step 2: Unified Timing Schema All native + JS startup timing lines carry tag `[StartupTiming]` with message format: ```