Skip to main content

Installation

This guide installs native-update into an existing Capacitor 8 project. If you do not yet have a Capacitor project, create one first with the official Capacitor docs. The v4 baseline is Node.js 24.16+, Capacitor 8, iOS 14+, and Android API 26+.

Prerequisites​

RequirementMinimumNotes
Node.js24.16.0The package declares and CI verifies this minimum.
Yarn4.x (recommended)This project is locked to Yarn 4.17; package consumers may use their app's package manager.
Capacitor@capacitor/core ^8.0.1Plugin's peer dependency. v7 and earlier are not supported by v4.
Xcode15+Required only for iOS builds. Apple Silicon Macs supported.
Android StudioHedgehog (2023.1) or newerRequired only for Android builds.
JDK21Used by the Android build and CI.
AndroidAPI 26+The plugin compiles/targets API 36.

Step 1 — Add the package​

yarn add native-update
# or: npm install native-update
# or: pnpm add native-update

This installs:

  • The TypeScript SDK (dist/esm/)
  • The CLI (cli/index.js, exposed as the native-update bin)
  • Android sources (android/src/main/ — auto-discovered by Capacitor's Gradle plugin)
  • iOS sources (ios/Plugin/ — referenced by NativeUpdate.podspec)

Step 2 — Sync native projects​

npx cap sync

This single command:

  • Copies the plugin's manifest-additions.xml into your Android AndroidManifest.xml
  • Adds the plugin to your android/app/capacitor.build.gradle
  • Adds the pod entry to ios/App/Podfile
  • Runs pod install on iOS (if Xcode is installed)

If you only want to sync one platform: npx cap sync ios or npx cap sync android.

Step 3 — iOS-specific setup​

Open the iOS workspace once after cap sync:

cd ios/App && open App.xcworkspace

The pod is now in your project. You do not normally need to touch Info.plist for the live-update feature, but background updates require these capabilities and Info.plist keys (covered in detail in the iOS platform guide):

  • Capability: Background Modes → Background fetch and Background processing
  • Info.plist: BGTaskSchedulerPermittedIdentifiers array containing your plugin's task identifier

Step 4 — Android-specific setup​

npx cap sync injects the merged manifest entries automatically. The plugin uses:

  • INTERNET (always granted)
  • ACCESS_NETWORK_STATE (for network-aware background updates)
  • POST_NOTIFICATIONS (Android 13+, only if you enable background-update notifications)
  • FOREGROUND_SERVICE and FOREGROUND_SERVICE_DATA_SYNC (only if you opt into background downloads)

Inspect the merged manifest at android/app/build/intermediates/merged_manifests/*/AndroidManifest.xml after a build to confirm. The detailed permission audit is in the Android platform guide.

Step 5 — Verify the install​

Add a quick verification call to your app entry point:

import { NativeUpdate } from 'native-update';

async function verify() {
  // Cheap call — does not hit the network or take any action.
  const ready = await NativeUpdate.isInitialized();
  console.log('[native-update] initialized?', ready);
}

verify();

Run your app:

npx cap run ios     # or: npx cap run android

A successful install logs [native-update] initialized? false (false because you have not called initialize() yet — that happens in the Quick Start). If you instead see "Plugin not implemented on android/ios", the native sources have not been picked up — re-run npx cap sync and clean the native build (./gradlew clean for Android, Product → Clean Build Folder for iOS).

Step 6 — (Optional) Install the CLI globally​

The CLI is shipped inside the native-update package and is invokable via npx native-update <command> immediately after step 1. If you want a global binary:

yarn global add native-update
# or: npm install -g native-update

native-update --help

You will use the CLI in the Quick Start to generate signing keys and create your first bundle.

Troubleshooting common install errors​

"Plugin not implemented on android"​

Run npx cap sync android, then in Android Studio do Build → Clean Project and Build → Rebuild Project. If still failing, open android/app/build.gradle and confirm implementation project(':native-update') is present (Capacitor's Gradle plugin should add this automatically).

"Plugin not implemented on ios"​

Run cd ios/App && pod install --repo-update. If you are on Apple Silicon and pod install fails with architecture errors, prefix with arch -x86_64 and re-run.

"Cannot find module 'native-update' or its corresponding type declarations"​

Restart your TypeScript server. In VS Code: Cmd+Shift+P → TypeScript: Restart TS Server. The package ships dist/esm/index.d.ts and is picked up via the types field in package.json, but editor caches sometimes lag.

peerDependencies warning on install​

native-update requires @capacitor/core ^8.0.1. If your project is on Capacitor 7 or earlier, upgrade Capacitor first: npx @capacitor/cli@latest migrate.

Bundle size concern​

The package is small (under 60 KB minified) and tree-shakeable. Importing only what you use is enough — there is no separate "lite" build.

Next steps​

  • Quick Start — wire your first OTA update in 5 minutes (3 of which are downloading native build tools).
  • CLI reference — for keys generate, bundle create, bundle sign.
  • Backend overview — the hosted service, or your own server.

Maintained by the Native Update team. Found a bug or an unclear step? Tell us.