@nativescript/capacitor

Full native platform API access for Capacitor apps, powered by the NativeScript runtime — SPM-first on iOS, a self-contained Gradle module on Android.

Write native code in TypeScript next to your web code, call it from your webview through the typed native proxy, and never touch your native projects: no CocoaPods, no build phases, no AppDelegate edits, no linker flags on iOS — and on Android no Application replacement, no manifest edits, no build.gradle grafting.

// in your web code
import { native } from '@nativescript/capacitor';

const version = await native.UIDevice.currentDevice.systemVersion.get;
native.openNativeModalView(); // your own helper, written in src/nativescript/

Requirements (8.x)

• Capacitor 8 app; on iOS using Swift Package Manager (the Capacitor 8 default; on Capacitor 6/7 use SPM mode)
• iOS 15+, Xcode with the iOS SDK
• Android minSdk 23+, Android SDK + JDK 17+ (for the on-demand metadata generation)
• For CocoaPods-based apps, use @nativescript/capacitor@5.

Getting started

In your Capacitor app (iOS platform added — npx cap add ios if you haven't):

npm install @nativescript/capacitor
npx nscap init      # scaffolds src/nativescript + npm scripts (additive & idempotent)
npm run build       # build your web assets as usual (any bundler)
npx cap sync ios
npx cap run ios

nscap init creates:

• 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 wiring nscap build into npx cap copy via Capacitor's capacitor:copy:before hook, so your native code always builds with your app

That's the whole setup. The NativeScript runtime arrives through SPM (NativeScript/ios-spm) when Capacitor syncs the plugin, and boots automatically with your app.

How it works

• Your src/nativescript/ TypeScript is bundled (esbuild, milliseconds) into your web assets and executed by the embedded NativeScript runtime with full platform API access.
• The webview's native object is a proxy: each dot-notation access marshalls to the runtime and back, promise-based.
• Platform API metadata ships inside the runtime's framework — zero configuration. Need more surface (pods, custom frameworks)? npx nscap metadata generates a custom metadata bin in seconds, and nscap build bundles it automatically.

CLI

nscap init        scaffold src/nativescript + npm scripts
nscap build       bundle native TS into <webDir>/nativescript (auto-runs on cap copy)
nscap metadata    generate custom platform metadata (--simulator for the sim SDK);
                  extra search paths via src/nativescript/metadata.json
nscap typings     generate iOS SDK TypeScript declarations matching your Xcode SDK

Debugging

Bridge marshalling logs are off by default:

import { nativeDebug } from '@nativescript/capacitor';
nativeDebug(true);

NativeScript-side console.log output appears in the system log (Xcode console, or log stream --predicate 'process == "YourApp"').

License

MIT