Configuration reference
Required fields, overrides, validation, and path resolution.
Start with the complete example in getting started,
then use the tables below to adjust it. The validator in
src/main.ts
defines which values are accepted.
Root fields
| Field | Required / default | Meaning |
|---|---|---|
name | Required | Lowercase kebab-case app label. |
appDirectory | Required | Expo app directory, resolved from the project root. |
bundleIdentifier | Required | Bundle identifier installed in the simulator. |
scheme | Required | URL scheme without ://; must match screenshot deep links. |
xcodeScheme | Required | Xcode scheme and basename of its .xcworkspace. |
iosProduct | Required | Built app filename, such as ExampleApp.app. |
apiEnvironment | Required | App-defined nonempty environment name. |
appearance | light | light, dark, system, or both. |
backupCodeEnv | Omitted | Name of an environment variable containing an optional setup credential. |
backupCode | Empty string | Literal setup value supported by the runtime; use backupCodeEnv instead for secrets. |
simulator | Required | Nonempty name, deviceType, and runtime. |
metro | Required | port, an integer from 1024 through 65535. Must be available. |
defaults | Required | All four stability settings below; there are no implicit timing defaults. |
screenshots | Required | Nonempty array of screenshot definitions. |
Names match ^[a-z0-9][a-z0-9-]*$. Schemes must be valid URL schemes and are
compared case-insensitively. All filesystem paths are relative to the project
root, not the JSON file's directory. Root backupCodeEnv rejects an unset
or whitespace-only variable and cannot be combined with a nonempty literal
backupCode. Unknown object keys are stripped by the current Zod object
schemas; double-check spellings rather than expecting unknown-key errors.
Stability settings
| Field | Validation | Meaning |
|---|---|---|
minimumWaitMs | Integer, at least 0 | Wait before sampling; included in the timeout budget. |
sampleIntervalMs | Integer, at least 50 | Delay between samples. |
stableSamples | Integer, at least 2 | Consecutive sufficiently similar frames required. |
timeoutMs | Integer, at least 1000 | Sampling time budget; must exceed minimumWaitMs. |
Values are numbers in milliseconds where named Ms. The quickstart's
750 / 250 / 3 / 15000 settings are examples, not built-in defaults. A blocked
simulator screenshot operation can outlast the sampling budget; this is not a
hard wall-clock deadline for the whole capture.
Screenshot fields and overrides
Every screenshot requires name and deeplink. The name follows the app-name
pattern and must be unique. The deep link must be a URL using the configured
scheme. Generated PNG filenames must also be unique after appearance expansion.
Optional fields:
state: onekeyorkey:value, or a nonempty array; see app states.optional: boolean, defaults tofalse; metadata, not a failure-policy switch.apiEnvironment,appearance, andbackupCode: override root values.minimumWaitMs,sampleIntervalMs,stableSamples, andtimeoutMs: override individual rootdefaultsfields. The merged settings must still validate.
backupCodeEnv is a root field, not a per-screenshot override. Avoid storing
secrets in per-screenshot literal values. Use separate configurations and an
environment variable when captures require different secret credentials.
both expands into light then dark, producing <name>-light.png and
<name>-dark.png. A single appearance produces <name>.png. With system,
Snapbot does not force a device appearance; it preserves the simulator's current
setting and passes system to your app callback.
Choose a dedicated simulator
Snapbot resolves the configured simulator by name. It creates a missing one
using the specified device type and installed runtime. Multiple simulators with
the same name are an error; the diagnostic lists their UDIDs. Inspect them
before manually deleting unwanted duplicates with xcrun simctl delete <udid>.
Use a dedicated simulator because Snapbot boots it, installs the app, adjusts
appearance and permissions, and shuts it down after the run.