Skip to content

Commit 67babea

Browse files
NathanWalkerNathanWalker
committed
docs: compiled releases (--compiled) and development options (TypeScript or SwiftUI)
1 parent d87ae36 commit 67babea

13 files changed

Lines changed: 1103 additions & 6 deletions

‎content/guide/pathways.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: 'Development options: TypeScript or SwiftUI'
3+
description: NativeScript is your development runtime, not your production runtime. Write SwiftUI and develop it live, or write TypeScript and compile the release to native code.
4+
contributors:
5+
- NathanWalker
6+
---
7+
8+
NativeScript has always run your app on a JavaScript runtime with direct access to every platform API. It now offers
9+
two development options that keep that experience and ship **no JavaScript runtime at all**:
10+
11+
| | 1. SwiftUI, live | 2. TypeScript, compiled |
12+
| -------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
13+
| **You write** | SwiftUI, in an Xcode project | TypeScript with `@nativescript/core` and the framework you like (Angular, Vue, React, Svelte, Solid, plain TypeScript) |
14+
| **While developing** | NativeScript runs your SwiftUI views live: each save is on screen in about 0.15–0.5 s, state kept | `ns run`: the JavaScript runtime with HMR, Chrome DevTools and the whole npm ecosystem, exactly as today |
15+
| **What ships** | Your Swift, built by Xcode as usual | Your app compiled to Swift (iOS) and Kotlin (Android) by `ns build --compiled` |
16+
| **Platforms** | iOS; Android live development, rendered by Jetpack Compose | iOS and Android |
17+
| **Status** | [Preview](/guide/swiftui-live) | [Alpha](/guide/publishing/compiled) |
18+
19+
Both rest on the same idea: **develop live, ship native.** The development runtime gives you instant feedback; the
20+
release is the native code a platform developer would have shipped.
21+
22+
## Which one fits
23+
24+
- **You know SwiftUI, or you are starting an iOS-first app in Swift**: take [SwiftUI, live](/guide/swiftui-live).
25+
You keep Xcode, Swift and your project as they are; NativeScript only shortens the edit-to-screen loop.
26+
- **You know web development, or you already have a NativeScript app**: take
27+
[TypeScript, compiled](/guide/publishing/compiled). Nothing changes while you develop. The release build is
28+
compiled instead of bundled.
29+
30+
The two meet at the release: both ship native code with no engine inside, and both are checked the same way,
31+
pixel by pixel against the build they replace.
32+
33+
## The JavaScript runtime is not going anywhere
34+
35+
A release on the JavaScript runtime (`ns build --release`) remains the default and is fully supported. Compiled
36+
releases are opt-in, per build or per platform, and you can switch back with `--no-compiled` at any time. See
37+
[Publishing](/guide/publishing/).

‎content/guide/publishing/compiled-android.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: 'Compiled releases: Android'
3+
description: Requirements, signing, threading annotations, R8 and mapping crashes back to TypeScript in a compiled Android release.
4+
contributors:
5+
- NathanWalker
6+
---
7+
8+
## Requirements
9+
10+
- **JDK 17** or newer and the **Android SDK**. The compiler ships its own Gradle wrapper.
11+
- macOS or Linux. Windows is not supported yet.
12+
- The app runs on **Android 7 (API 24)** and later.
13+
14+
## Build, sign, run
15+
16+
A compiled build is a release build, and Android signs every release, so all four `--key-store-*` options are
17+
required:
18+
19+
```bash
20+
ns build android --compiled --key-store-path release.keystore --key-store-password … \
21+
--key-store-alias … --key-store-alias-password … # signed .apk; add --aab for a bundle
22+
ns run android --compiled --key-store-path … # build, install and launch
23+
```
24+
25+
They sign as Android Studio does. To try a build before you have your upload key, make a throwaway keystore (see
26+
[Getting started](/guide/publishing/compiled-getting-started#_2-build-and-run)).
27+
28+
Android installs an app over another only when both are signed with the same key. Moving between a debug build
29+
(signed with the SDK's debug key) and a release signed with another key fails with "a previously installed package
30+
of the same name has a different signature": uninstall first (`adb uninstall <app id>`).
31+
32+
## The Gradle project
33+
34+
`platforms/compiled/android` is a Gradle project, regenerated on every build. App_Resources carry over as the CLI
35+
carries them: `res/`, `AndroidManifest.xml` (merged with plugins'), `app.gradle` and `before-plugins.gradle`, and
36+
fonts. Plugins' Java, Kotlin and Gradle dependencies are linked unchanged.
37+
38+
The kit marks main-thread code `@UiThread` and code that may run on any thread `@AnyThread`, and Android lint
39+
checks calls against them.
40+
41+
`fetch` and `XMLHttpRequest` are not available on Android yet. They are on iOS.
42+
43+
## Minification (R8)
44+
45+
Members reached by name at run time (a method called on an `any` value, `typeof x.getFoo`, `'getFoo' in x`) are
46+
kept from R8's renaming by a scan of the compiled code. A name computed at run time (`x[name]()` with `name` built
47+
from strings) isn't found by the scan: keep such members with a ProGuard rule in
48+
`App_Resources/Android/app.gradle`, and check the minified release on a device.
49+
50+
By default every class and member of the kit is kept. `android: { release: { narrowKitKeeps: true } }` keeps only
51+
what the kit's reflection needs and lets R8 remove the rest: on Recipes (Vue) the kit's dex goes from 3.3 to 2.0 MB
52+
and the APK from 2.44 to 1.92 MB. It is opt-in until it has been checked on larger apps; under it, a kit member
53+
reached only through a computed name is removed.
54+
55+
## Crashes and debugging
56+
57+
Kotlin has no source-location directive, so the build writes a line table (`source-lines.json`) beside the Gradle
58+
project. `ns-native-retrace` reads a stack trace in your TypeScript lines: it runs R8's retrace with the build's
59+
`mapping.txt`, then maps your app's frames to your files and the kit's frames to `@nativescript/core` files.
60+
61+
```bash
62+
adb logcat -d -s AndroidRuntime | npx ns-native-retrace platforms/compiled/android
63+
npx ns-native-retrace platforms/compiled/android crash.txt # a trace saved from your crash reporter
64+
```
65+
66+
Keep `mapping.txt` and `source-lines.json` with each release you upload. When the Kotlin compile fails, `ns build`
67+
prints each error at the TypeScript line it came from.
68+
69+
`error.stack` lists native frames, such as `class.method(File.kt:line)`, which `ns-native-retrace` maps. Uncaught
70+
errors go to `Application.uncaughtErrorEvent` and are logged as `***** Fatal JavaScript exception *****` (logcat
71+
tag `JS`). Debug a compiled release in Android Studio, as a native app.
72+
73+
## Build times
74+
75+
Measured on a blank app with R8, 2026-10-13: the first build takes a minute or two, a one-line change about 45 s.

‎content/guide/publishing/compiled-configuration.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: 'Compiled releases: configuration'
3+
description: The release options in nativescript.config.ts, how the flag and the config combine, and what an app may need to add.
4+
contributors:
5+
- NathanWalker
6+
---
7+
8+
## Turning it on
9+
10+
`--compiled` on `ns build`, `ns run` or `ns deploy` compiles that release, and implies `--release`. To make it the
11+
default, set `release.compiled` in `nativescript.config.ts`:
12+
13+
```ts
14+
// nativescript.config.ts
15+
export default {
16+
id: 'org.example.app',
17+
release: {
18+
compiled: true, // every release build is compiled
19+
},
20+
android: {
21+
release: { compiled: false }, // except Android's
22+
},
23+
} as NativeScriptConfig
24+
```
25+
26+
- `--compiled` and `--no-compiled` win over the config.
27+
- `ios.release` and `android.release` merge over the top-level `release`; object options merge by key.
28+
- Debug builds always run on the JavaScript runtime.
29+
30+
The compiler reads `nativescript.config.ts` without running it: it takes the object literal after `export default`
31+
(an `as` or `satisfies` is fine). A value computed in code, or a config exported through a variable, isn't seen.
32+
33+
## Options
34+
35+
All of them go in `release`, or in a platform's `release`.
36+
37+
| Option | What it does |
38+
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
39+
| `compiled` | Release builds are compiled instead of bundled for the JavaScript runtime. |
40+
| `pluginReplacements` | `{ 'package': './path.ts' }`: replaces a package with a module of yours that has the same exports. For plugins that only make sense with a JavaScript runtime, such as over-the-air updates. |
41+
| `pluginSources` | `{ 'package': '../checkout' }`: compiles a plugin from a local checkout of its source instead of fetching the published revision. |
42+
| `allowUnimplementedProperties` | Builds even when the app sets a core property the compiled build doesn't apply, with a warning for each. |
43+
| `allowCoreMismatch` | Builds with a `@nativescript/core` other than the one the compiler was made from, with a warning. |
44+
| `allowUntestedFrameworks` | Builds with a framework version outside the [tested ones](/guide/publishing/compiled-differences#tested-framework-versions), with a warning. |
45+
| `narrowKitKeeps` | Android: R8 keeps only what the kit's reflection needs. See [Android](/guide/publishing/compiled-android#minification-r8). |
46+
| `generatedKit` | Android: `false` builds on the older hand-written kit instead of the one generated from core. |
47+
48+
## What your app may need
49+
50+
Most apps need nothing but the flag. Of the apps compiled so far, none changed their own source; some added
51+
configuration:
52+
53+
| Situation | What to do |
54+
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
55+
| A plugin that only makes sense with a JavaScript runtime (over-the-air updates) | `pluginReplacements: { '@norrix/client-sdk': './release/norrix.ts' }` |
56+
| A plugin whose published source can't be found, or doesn't match its JavaScript | `pluginSources: { 'some-plugin': '../some-plugin' }` |
57+
| You patch a plugin with patch-package | Write the same patch against the plugin's TypeScript source, in `native-release/patches/<package>+<version>.patch`. The compiler compiles the source, not the published JavaScript your patch changes. |
58+
| You patch `@nativescript/core` with patch-package | The compiler recognizes common core patches and applies their effect. One it doesn't recognize stops the build. |
59+
| An `Info.plist` with no `UIApplicationSceneManifest` (older templates) | Nothing: the build adds the template's and says so. |
60+
61+
## Hooks
62+
63+
Your project's hooks run as they do for a JavaScript build: `before-prepare`/`after-prepare` and
64+
`before-buildIOS`/`after-buildIOS` (`buildAndroid` on Android), with the same arguments. In a compiled build
65+
`projectRoot` is `platforms/compiled/<platform>`, so a hook that edits the Xcode or Gradle project under
66+
`platforms/ios` or `platforms/android` has nothing to change.

0 commit comments

Comments
 (0)