Configuration

Swiftpatch reads configuration from three places, in precedence order:

1. Props passed to <SwiftPatchProvider config={...}> in JavaScript (highest precedence).
2. Native config — Info.plist on iOS, strings.xml on Android. Written by swiftpatch init.
3. Defaults — sensible for 95% of apps.

You usually only need to touch the Provider config. Native values come from swiftpatch init.

The minimum config

<SwiftPatchProvider config={{ debug: __DEV__ }}>
  <App />
</SwiftPatchProvider>

That's it. deploymentKey is optional when swiftpatch init has written it to the native config.

SwiftPatchUserConfig — the three public options

interface SwiftPatchUserConfig {
  deploymentKey?: string;
  debug?: boolean;
  onUpdate?: (release: ReleaseInfo) => void;
}

Option	Default	Description
deploymentKey	null	Channel-scoped read key. Omit if swiftpatch init embedded it in native config.
debug	false	Emits verbose SDK logs via console.log / native logcat / NSLog. Do not enable in production.
onUpdate	undefined	Called once per new release with the ReleaseInfo payload. Useful for triggering custom UI or analytics.

Advanced options (full SwiftPatchConfig)

Expose these through the Provider's config prop. All are optional and internal-but-stable:

interface SwiftPatchConfig extends SwiftPatchUserConfig {
  appId?: string;
  serverUrl?: string;
  checkOnResume?: boolean;
  checkInterval?: number;
  installMode?: InstallMode;
  mandatoryInstallMode?: InstallMode;
  customHeaders?: Record<string, string>;
  publicKey?: string;
  autoStabilizeAfterLaunches?: number;
  crashDetectionWindowMs?: number;
  maxCrashesBeforeRollback?: number;
  autoStagingInDev?: boolean;
}

Option	Default	Description
appId	null	Stable app identifier from the dashboard. When set, the SDK auto-resolves (and auto-rotates) the deployment key from the server.
serverUrl	https://api.swiftpatch.io/api/v1	Override the backend (self-hosted or staging).
checkOnResume	true	Check for updates every time the app foregrounds.
checkInterval	0	Minimum ms between checks. 0 means check on every resume.
installMode	ON_NEXT_RESUME	When to apply a ready non-mandatory update. See install modes.
mandatoryInstallMode	IMMEDIATE	When to apply a ready mandatory update.
publicKey	null (reads from Info.plist / strings.xml)	Override the Ed25519 verifier public key.
autoStabilizeAfterLaunches	2	Promote NEW slot to STABLE after N crash-free cold starts.
crashDetectionWindowMs	10_000	How long after launch a crash counts against the freshly-applied bundle.
maxCrashesBeforeRollback	2	Number of crashes before auto-rollback triggers.
autoStagingInDev	false	Force the STAGE environment when __DEV__ is true.

Install modes

enum InstallMode {
  IMMEDIATE = 'immediate',         // Restart now
  ON_NEXT_RESTART = 'onNextRestart', // Apply on next cold start
  ON_NEXT_RESUME = 'onNextResume', // Apply when app foregrounds
}

Defaults are tuned for UX:

• Non-mandatory updates use ON_NEXT_RESUME — the user sees the update the next time they come back.
• Mandatory updates use IMMEDIATE — restart the moment the download finishes.

Native config

swiftpatch init writes these into your native files automatically.

iOS — Info.plist

<key>SwiftPatchDeploymentKey</key>
<string>dep_xxx...</string>

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.swiftpatch.bg-refresh</string>
</array>

<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
  <string>processing</string>
</array>

Optional extras:

Key	Purpose
SwiftPatchProjectId	Project ID. Optional.
SwiftPatchServerUrl	Custom API endpoint.
SwiftPatchPublicKey	Public key for signature verification.
SwiftPatchAppId	Stable app id for key auto-resolution.

Android — strings.xml

<resources>
  <string name="swiftpatch_deployment_key">dep_xxx...</string>

  <!-- Optional -->
  <string name="SwiftPatchProjectId">proj_xxx</string>
  <string name="SwiftPatchServerUrl">https://api.swiftpatch.io/api/v1</string>
  <string name="SwiftPatchPublicKey">...</string>
</resources>

.swiftpatchrc

Per-project config for the CLI. Commit this file — it does not contain secrets.

.swiftpatchrc

{
  "appId": "app_abc123",
  "app": "my-app",
  "platform": "ios",
  "signingKey": "./.swiftpatch/keys/private.pem"
}

Field	Description
appId	Stable app id from the dashboard.
app	App slug for human-friendly logs.
platform	ios | android — default platform for swiftpatch deploy.
signingKey	Path to the Ed25519 private key.

Keep the private key out of Git

.swiftpatch/ is added to .gitignore by swiftpatch init. Never commit private.pem. For CI, store the key as an encrypted secret — see CI/CD.

Verifying the native config

import { getNativeConfig } from '@swiftpatch/react-native';

const cfg = await getNativeConfig();
// {
//   projectId: string | null,
//   appToken: string | null,
//   appId: string | null,
//   deploymentKey: string | null,
//   serverUrl: string | null,
//   publicKey: string | null,
// }

Use this in a useEffect to verify swiftpatch init ran correctly.

Next steps

• Provider reference — opinionated UI props (autoShowBanner, theme, ...).
• Methods — the imperative Swiftpatch.* surface.
• CLI CI/CD — configure production deploys.

Architecture

The SDK is a state machine. Each transition maps to a public method or an internal verification step — and every failure path returns to Idle without touching the running bundle.