Installing @nativescript/capacitor ​

Version note

8.x works with Capacitor 8 apps on iOS and Android (on iOS, Capacitor 6/7 apps must use SPM mode).

Using CocoaPods? Use @nativescript/capacitor@5 and the v5 docs.

  • iOS: no CocoaPods, no Podfile edits, no AppDelegate changes, no Xcode build phases, no linker flags. The NativeScript runtime arrives as a Swift Package (NativeScript/ios-spm) when Capacitor syncs the plugin, and platform API metadata ships inside the runtime's framework with zero configuration.
  • Android: no Application replacement, no manifest edits, no build.gradle grafting, nothing copied into your repo. The plugin is a self-contained Gradle module that Capacitor wires up on sync; nscap build fetches the runtime once (cached) and generates platform metadata automatically.

1. Start from a Capacitor app ​

Follow the Ionic or Capacitor getting started guide, and make sure your platforms are added:

bash
npx cap add ios
npx cap add android

2. Install and initialize ​

bash
npm install @nativescript/capacitor
npx nscap init

nscap init is additive and idempotent — it only creates files and npm scripts, never touching your Xcode project:

  • src/nativescript/index.ts — your native TypeScript entry, with a working native modal example
  • src/native-custom.d.ts — strongly type your own native.* helpers
  • npm scripts that wire nscap build into Capacitor's capacitor:copy:before hook, so your native code builds automatically on every npx cap copy / npx cap sync

3. Build and run ​

bash
npm run build       # build your web assets as usual (any bundler)
npx cap sync
npx cap run ios     # and/or: npx cap run android

That's the entire setup. At app launch you'll see the example's greeting in the native console, and from your web code you can immediately do:

ts
import { native } from '@nativescript/capacitor';

const version = await native.UIDevice.currentDevice.systemVersion.get;
native.openNativeModalView(); // the scaffolded example helper

Requirements ​

  • Capacitor 8 app (on iOS, SPM is the Capacitor 8 default — or Capacitor 6/7 with SPM mode)
  • iOS 15+, Xcode with the iOS SDK
  • Android minSdk 23+, Android SDK, JDK 17+
  • Node 18+

Troubleshooting ​

Blank webview after adding NativeScript ​

If the app launches to a blank screen, your web assets were likely never built — run your web build (e.g. npm run build) before npx cap sync. The NativeScript build hook creates the web assets folder, which can mask Capacitor's usual "web assets directory not found" error on brand-new apps.

Where do my NativeScript console.logs go? ​

To the native system log, not the webview console. On iOS, see them in the Xcode console, or:

bash
# iOS simulator
xcrun simctl spawn booted log stream --predicate 'process == "App"'

On Android they appear in logcat under the JS tag:

bash
adb logcat -s JS

First build is slow ​

The very first iOS build downloads the NativeScript runtime binaries through Swift Package Manager, and the first nscap build with an Android platform fetches the Android runtime once. Both are cached; subsequent builds are fast.