RFC: --compiled — release builds compiled to Swift and Kotlin, with no JavaScript runtime

[NathanWalker]

RFC: --compiled — release builds compiled to Swift and Kotlin, with no JavaScript runtime

Status	Proposed — public preview. 9.2.0-alpha.0 of nativescript, @nativescript/core and @nativescript/compiler is on npm (dist-tag alpha)
Implementation	Compiler, runtimes and kit generation: packages/compiler on feat/native-kit · CLI: feat/native-release · issue intake: NativeScript#11546
Docs	docs#203 (the "TypeScript Compiled" pages and the generated support table)
Related	rfcs#57 (ns:swift), rfcs#58 (ns:native)

Summary

NativeScript has never offered a way to ship without a JavaScript runtime. This RFC proposes one, as an option beside the JavaScript release:

ns build ios --compiled
ns build android --compiled --key-store-path …

1. Development doesn't change. ns run and ns debug still run on the JavaScript runtime with HMR. --compiled changes only how a release is built.
2. The whole app compiles: your code, its framework, its plugins and @nativescript/core itself, to Swift and Kotlin. The output is an ordinary Xcode or Gradle project in platforms/compiled/<platform>. No JavaScript engine ships.
3. Core isn't ported; it's compiled. The native "kit" is generated from core's own TypeScript, so there is one source for both releases. Each core release publishes a matching @nativescript/compiler.
4. JavaScript's semantics are kept, by a small runtime in each language, and checked byte for byte against Node. What can't be translated exactly is a build error with the TypeScript file and line, never a silent change in behavior.
5. It's opt-in per release. release: { compiled: true } in nativescript.config.ts makes it the default; --no-compiled builds a JavaScript release instead.

Motivation

Size, memory and launch. A JavaScript release carries an engine, the framework's JavaScript and a bundle. Measured on our own apps against their own JavaScript releases:

Measure	JavaScript release	Compiled release
Guitar Pocketbook, Android App Bundle	28.1 MB	14.6 MB
OpenJS app, iOS .ipa	27.8 MB	17.3 MB
Memory after launch, iOS (bench app, simulator)	41.0 MB	18.0 MB
Memory after workloads, Android (bench app, emulator)	235 MB	83 MB
Launch to first frame, Android (bench app, emulator)	2,304 ms	1,615 ms

Typed code runs at native speed. On iOS, V8 runs without a JIT. Against it, typed method calls and field writes ran about 100 times faster compiled, and a numeric n-body simulation 11 times faster.

Teams that can't ship a JavaScript runtime. Some organizations require native code they can audit, or simply want "a native app" with no qualifiers. Today they leave NativeScript to get it. Compiled output is ordinary Swift 6 and Kotlin that opens in Xcode and Android Studio, and crash reports and debuggers point at the TypeScript lines.

NativeScript is unusually well placed to do this. Compiling a dynamic language to native code is hard because the compiler must guess what each call means. NativeScript removes most of the guessing:

• Every native call is already typed. @nativescript/types-ios and types-android are generated from the SDKs. A call to UIImage.systemImageNamedWithConfiguration(...) becomes the Swift call, with no bridge to emulate.
• The platform layer is already TypeScript. Core's *.ios.ts and *.android.ts drive UIKit and Android views directly, so the compiled app uses the real views, laid out by core's own code. That's why compiled galleries match their JavaScript builds pixel for pixel.
• Frameworks compile with their own compilers. Vue, Angular and Svelte templates go through each framework's compiler, so their syntax is never re-implemented.

Guide-level explanation

Building

npm install --save-dev @nativescript/compiler

ns build ios --compiled                 # simulator .app (--compiled implies --release)
ns build ios --compiled --for-device    # device archive and .ipa
ns run ios --compiled                   # build, install, launch
ns build android --compiled --key-store-path release.keystore … --aab

Or make it the default for release builds:

// nativescript.config.ts
export default {
  id: 'org.example.app',
  release: {
    compiled: true,
    pluginReplacements: { 'moment': './native-release/moment-stand-in.ts' },
  },
  android: { release: { compiled: false } },   // per-platform override
} as NativeScriptConfig;

release is also the compiler's options object (pluginReplacements, pluginSources, stubPlugins, allowUnimplementedProperties). A platform's release merges over the top-level one.

When something can't compile

The build stops with the TypeScript file and line and the reason. For example, eval in a reachable module, or a core property the kit doesn't implement yet. There are escape hatches with warnings (allowUnimplementedProperties, --allow-core-mismatch, --allow-untested-frameworks), and --no-compiled builds the JavaScript release.

Reporting a failure

When a compiled build fails, the CLI saves a report and prints one line: ns compiled report <platform>. It collects versions, platform, toolchain and the diagnostic with paths and secrets redacted, and shows all of it before anything is sent; the default answer is no. Each report carries a signature of the error. An existing issue with that signature gets a 👍; otherwise a labelled issue is opened through an issue form (#11546). Each report becomes a differential test case, and the fix lands once in the compiler.

What strict buys you

TypeScript's types are erased: a parameter typed Person can receive undefined at run time. The compiler follows one rule: a type is a contract only where TypeScript can prove it.

function greet(p: Person): string { return 'Hello ' + p.name; }

// the module is strict: p is always a Person
func greet(_ p: Person) -> String { "Hello " + p.name }

// the module isn't strict: p is held as optional and checked where JavaScript would throw
func greet(_ p: Person?) throws -> String { "Hello " + (try jsUnwrap(p, "name")).name }

Both behave as JavaScript does. The strict form is smaller, faster and reads like hand-written Swift. Core and plugins compile under their own settings, so an app's strict only affects the app's code.

What won't work

Some JavaScript can't exist without an engine, and is refused at build time:

• code that doesn't exist until run time: eval, new Function, downloaded code and over-the-air JavaScript updates;
• reflection over the language: Proxy, Reflect, with, SharedArrayBuffer, FinalizationRegistry;
• patching core's prototypes or registering behavior by name at run time.

Apps that depend on these keep the JavaScript release.

Reference-level details

Pipeline

1. Each framework's own compiler turns templates into TypeScript classes plus a view tree.
2. The app, its plugins' TypeScript source and core are type-checked as one program, against core's real declarations and the platform SDK typings. Only modules reachable from the entry compile.
3. The program is translated to Swift and Kotlin. Arrays are shared references, Map and Set keep insertion order, promises and microtasks follow the spec, numbers print as JavaScript prints them, and any stays a dynamic value.
4. Native calls map to the names Swift or Kotlin expose, and @NativeClass subclasses become real native subclasses.
5. Core, compiled the same way, links as a Swift package and a Kotlin library (the kit). Framework support is layered as separate kits on top of the core kit, auto-detected from the project.
6. Xcode or Gradle builds the project. Plugins' own native code links as usual.

Runtime model

• Threads. Each JavaScript realm lives on one thread; the app's is the main thread. Native callbacks enter through guarded entry points that hop to it. Swift output is Swift 6 with main-actor isolation; Kotlin uses lint-checked @UiThread/@AnyThread.
• Errors. A throwing render, list row, route or native callback reports through Application.uncaughtErrorEvent and leaves that region empty. Calling an API newer than the running OS throws a catchable TypeError. A CI gate fails any change that adds a new crash site ("trap") to the kit.
• Values from untyped places (non-strict modules, any, as, native returns) are held loosely and converted where used, checked only where JavaScript would throw.

Plugins and npm packages

Plugins compile from their TypeScript source, resolved from the published package or its repository at the published version (including relocated monorepos and unpublished tags). Mixed Swift and Objective-C plugins, header-only modules and vendored static pods are linked. Three kinds can't compile as they are, and release.pluginReplacements maps the package to a typed module in the app:

Kind	Example	Why
Binary-only (no source)	nativescript-ui-listview	Nothing to compile
Dynamic ES5/UMD bundles	moment	Prototype mutation and arguments overloading have no static form
Reads the JavaScript VM	stacktrace-js	There is no VM

Keeping in step with core

• The kit is regenerated from core's TypeScript; a core change reaches compiled apps the same way it reaches JavaScript apps.
• The core repo's Compiler workflow runs on pushes that touch core, the compiler or the type definitions. It regenerates both kits, runs the differential suites against Node (Swift also at -Osize), builds the kit with warnings as errors, lints Kotlin's thread annotations, and builds and launches an app on an Android emulator and the two newest iOS simulators.
• test262 (a 9,330-test subset) and a program fuzzer run nightly against baselines.
• Each core release tag publishes a matching @nativescript/compiler; the compiler refuses a core version it wasn't generated from.

Where it stands

Area	State
Core kit	Differential suites pass apart from a known list: 274 cases in Swift, 184 in Kotlin
Frameworks	XML with TypeScript, Vue, Angular and Svelte 5 galleries match their JavaScript builds at 0 px on iOS and Android
Real apps	Guitar Pocketbook (WebGPU, audio worker, foldables) and the OpenJS app (Angular, eight plugins) are in the App Store and Google Play as compiled releases. A large private production app (about 60 plugin packages, rxjs, NgRx) runs on the iOS simulator; its remaining screens and Android are in progress
Generated code	A review held to native engineers' standards: Kotlin "a clean yes", Swift "yes" after five follow-ups, all merged
Exact semantics	About half of the accepted test262 cases, and 49% (Swift) / 44% (Kotlin) of fuzzed programs, match Node exactly. Every difference is a tracked known failure, and the support table is generated from them
Performance	Wins on launch, memory and typed code. Loses in the runtime library (JSON about 3× and stringify about 6× slower than V8 on iOS, regex, sort, Map/Set, async) and Android list scrolling
Build time	Blank app, no-change rebuild 14 s; one-line edit about 55 s; a clean build of a mid-size app about 4 minutes

Drawbacks

• Two release modes to support. Bug reports need to say which one; ns compiled report does, but triage still gets a new question.
• Semantics are close, not identical. Some differences are inherent: Swift strings can't hold a lone UTF-16 surrogate, and error.stack shows native frames. Others are work in progress (see above).
• No over-the-air updates for compiled releases.
• The runtime library is slower than V8's C++ builtins for JSON, regex and collections-heavy code.
• Plugins are the long tail. Core and the frameworks held up on real apps; most of the work on the large app was in its dependencies.

Alternatives considered

Alternative	Why not
Re-implement the platform elsewhere (Apportable, Windows Bridge for iOS)	An open-ended surface that never reaches its long tail. Core already drives the real views.
A hand-written native core	Our first version. It drifted from the real core.
Compile typed JavaScript inside the engine (Static Hermes)	The app still ships a VM, a garbage collector and the framework's JavaScript.
Business-logic-only translation (J2ObjC)	Leaves the UI on the JavaScript runtime, where most of the cost is.
Approximate what can't be translated	A passing build would no longer mean the same program. Refusing with a file and line keeps it honest.
Keep improving the JavaScript runtime only	Worth doing regardless, but it can't remove the engine's size and memory floor.

Adoption plan

1. Consolidate (in progress): land the large app's fixes as compiler changes with test cases, split its plugin work into reviewed branches, and re-run the milestone checks.
2. Public preview, 9.2.0-alpha.1: announce to core contributors and selected community members; merge the docs and the issue form; label compiled issues.
3. Plugins round: validate the most-used plugins and publish the results in the support table.
4. Performance round: the runtime library and typed member access (the cause of the Android scrolling gap).
5. Beta, when the criteria below are agreed and met.
6. Merge feat/native-kit into main, with the Compiler workflow required on core PRs.

Unresolved questions

1. Beta criteria. For example: N community apps building and matching their JavaScript release, no open crash-class issues, and the support table stable for two core releases. What would the TSC want to see?
2. Ownership. Who reviews compiler PRs, and should a core PR that breaks compiled output block, or warn, in CI?
3. Where it lives. packages/compiler in the core monorepo (current, so the kit regenerates with every core change), or its own repository?
4. Angular. Keep the compiler's own implementation of DI, Router, HttpClient and Forms, or compile @angular/core and friends from source, as rxjs and NgRx already are?
5. Binary-only plugins. A build error with an explicit opt-in, or a placeholder view with a warning?
6. Strictness. Should the build report where an app's code was compiled loosely (a planned strictness.json), and should ns create templates default to strict?
7. Native imports. How should compiled builds treat ns:native specifiers from rfcs#58? In a compiled build every native reference is already static, so they could map one-to-one to Swift module imports and Kotlin packages.

[NathanWalker]

• Most compiler reports will have good detail to act on (not much maintenance burden there on triage and action); happy to lead those review efforts
• It could live in it's own repo outside of core but keeping it with core aligns it's self maintaining auto-gen as core evolves on each release better