RFC: ns metadata trim — ship only the native API metadata an app uses, on every NativeScript host

[NathanWalker]

RFC: ns metadata trim — ship only the native API metadata an app uses, on every NativeScript host

Status	Proposed. Draft implementation, working on macOS, the iOS simulator and an Android emulator
Implementation	CLI: nativescript-cli#6203. Generator fix: NativeScript/runtimes@cb26a2b on android-react-native
Builds on	ns-metadata-symbols, objc-metadata-generator filtering and build-tools/metadata-filter on the android-react-native branch of NativeScript/runtimes
Related	runtimes#105 (@nativescript/react-native on macOS), nsh integration demo: nstudio/native-shell-with-ns (private for now)

Summary

Every NativeScript app ships metadata for its platform's entire SDK, and most of it is never used. This RFC proposes one command that fixes that for any host running the NativeScript runtime:

ns metadata trim macos dist/bundle.js --analyzer <path> --generator <path> --framework NativeScript.framework

1. It starts from the JavaScript that actually ships. It reads the emitted bundle, so app code, plugins and framework code all count.
2. It keeps what's named, and what that depends on. The runtime's generators already close over superclasses, protocols and signature types.
3. If usage can't be bounded, it stops. Dynamic global access or eval means nothing is trimmed, rather than something being removed by guesswork.
4. It isn't tied to a project layout. It takes bundle paths and an install target. nsh is the first host, and @nativescript/macos-node-api, @nativescript/react-native and standard ns projects can follow without a new pipeline.
5. It builds on native-api-usage.json, rather than replacing it. Declared rules from the app and its plugins are merged with what the analysis finds.
6. It's opt-in. Nothing changes for anyone who doesn't run it.

Motivation

Metadata is the largest part of the runtime's weight. Measured on a showcase app embedding NativeScript in nsh:

	macOS	iOS simulator	Android emulator
API metadata, full SDK	4.7 MB	4.6 MB	2.9 MB
API metadata, trimmed	0.67 MB	0.83 MB	0.81 MB
Framework, compressed, full SDK	2.36 MB	1.84 MB	n/a
Framework, compressed, trimmed	0.95 MB	0.84 MB	n/a
Idle memory added, full SDK (blank app)	+26 MB	+16 MB	+6 MB
Idle memory added, trimmed (blank app)	+6 MB	+9 MB	not isolated
Runtime startup, full SDK (blank app)	about 54 ms	about 36 ms	about 35–50 ms
Runtime startup, trimmed (blank app)	about 37 ms	about 17 ms	no clear change

Memory and startup fell along with the metadata, but how much each part of runtime startup contributes hasn't been profiled. On Android, filtering also enables R8. That took the APK from 23.8 to 21.4 MB and total memory from 50.0 to 40.3 MB, mostly from shrunk code, so the metadata's own effect on memory isn't isolated.

Embedders feel this most. When NativeScript is a capability added to another framework (nsh, React Native), its footprint is judged on its own. "Adds 0.9 MB" and "adds 2.4 MB" are different conversations.

The pieces exist, but aren't reachable as one feature. The android-react-native branch has a Rust analyzer for Apple, a harvester and seed for Android, and generator closures. NS_METADATA_AUTO_FILTER works inside an Xcode build phase and -PnsFilterMetadata inside Gradle. Hosts that don't use those build systems the same way, such as prebuilt frameworks, have no path at all, and the prebuilt framework still carries its full embedded metadata.

Guide-level explanation

Apple

ns metadata trim ios dist/bundle.js \
  --analyzer  node_modules/.../ns-metadata-symbols \
  --generator node_modules/.../objc-metadata-generator \
  --framework path/to/NativeScript.framework \
  --out build/trim

This writes build/trim/metadata.ios.arm64.nsmd, the whitelist it used, and a copy of the framework with the trimmed metadata embedded and the binary shrunk to fit. Without --framework, you get the .nsmd to place yourself.

Android

ns metadata trim android dist/bundle.js --android-project platforms/android

This writes whitelist.mdg. Build with -PnsFilterMetadata, so the generator closes over dependent types and R8 keeps what JS reaches.

Keeping or removing specific APIs

Existing native-api-usage.json files keep working. In a NativeScript project, the app's file and its plugins' files are found automatically for iOS and Android. Other hosts pass them explicitly, and one-off additions can go on the command line:

ns metadata trim macos dist/bundle.js --native-api-usage native-api-usage.json ...
ns metadata trim ios dist/bundle.js --keep 'MapKit:*' ...

When it refuses

A bundle that aliases globalThis, reads a global through a computed name, or uses eval can't be bounded:

Could not determine which native APIs this app uses, usually because the bundle reads
globals dynamically (for example an alias of globalThis, or eval). Nothing was trimmed.

typeof NSStatusBar !== "undefined" and direct references analyze cleanly, so feature detection doesn't need to change.

Relationship to native-api-usage.json

Metadata filtering and this command use the same mechanism: the same Module:Symbol patterns, and the same whitelist.mdg and blacklist.mdg semantics in the generators. They are two layers:

	native-api-usage.json	ns metadata trim
Role	What people declare	What the bundle shows
Written by	App and plugin authors, by hand	Derived from the emitted JavaScript
Applied	During an ns project's Xcode or Gradle build	Any host, including prebuilt frameworks
Can remove something the app references	Yes, with blacklist	Only through a declared blacklist
Unbounded usage	Not detected; a missing entry is undefined at run time	Stops and trims nothing

The merge follows the rules ns prepare already applies:

kept    = analysis + app whitelist + plugin uses (when whitelist-plugins-usages)
removed = app blacklist + plugin blacklist (when whitelist-plugins-usages)

One difference is deliberate. An app with no file of its own still keeps what its plugins declare, because declarations here can only add to the analysis. Plugin blacklists apply only when an app opts in.

A plugin that reaches an API by a computed name is exactly the case analysis can't see, and its existing uses entry covers it. So this layering makes declarations more useful rather than obsolete.

A blacklist entry can't remove a type a kept API's signature needs. On Apple platforms the generator keeps the type, and on Android the build fails and names it. Anyone blacklisting a name for confidentiality should check the generated metadata.

Where this adds the most. Hosts with a prebuilt framework have no other path, since rules alone can't change metadata already embedded in the binary. In a standard ns project the overlap is larger: NS_METADATA_AUTO_FILTER and -PnsFilterMetadata automate much of this inside Xcode and Gradle, and this command isn't wired into ns build yet. Its value there is one entry point and one set of safety rules.

Reference-level details

Pipeline

ns metadata trim <platform> <bundle...>
  validate bundles exist
  collect declared rules (native-api-usage.json, --keep)
  toolchain.analyze    bundle + kept rules -> filter patterns
  stop if unrestricted
  toolchain.generate   patterns -> metadata
  toolchain.install    metadata -> where the host reads it

Step	Apple	Android
Analyze	ns-metadata-symbols (Oxc)	The runtime's seed.js / harvest.js
Closure	objc-metadata-generator resolveRefs	MDG enforceClosure
Generate	Run by the CLI against the Xcode SDK	Run by Gradle
Install	Rewrite __objc_metadata in a framework copy, or leave the .nsmd	whitelist.mdg

The extension point

Everything host- or platform-specific sits behind one interface:

interface IMetadataToolchain {
  readonly platforms: string[];
  analyze(options): Promise<IMetadataUsage>;
  generate(usage, options): Promise<{ metadataPath?; metadataBytes? }>;
  install(usage, metadataPath, options): Promise<{ installedTo?; replacedBytes?; nextStep? }>;
}

How hosts adopt it

Host	JS to analyze	Where metadata is read from	State
nsh	.nsh/out/bundle.js	Embedded __objc_metadata; Android assets/metadata	Implemented and verified
@nativescript/macos-node-api	The app's bundle	Embedded in NativeScript.framework	--framework was exercised with this package's framework, inside nsh. Not run in a plain Node process
@nativescript/react-native (runtimes#105)	The Metro bundle	metadata.{ios,macos}.{arch}.nsmd, resolved by bundledMetadataPath	Not implemented. The CLI already writes that file naming, so it needs an install step
Standard ns projects	platforms/*/.../app after webpack or Vite	Xcode -sectcreate, Android assets/metadata	Declared rules are read from the project. Not wired into prepare or ns build yet

Each new host needs to answer two questions: where is the emitted JS, and where does metadata go. The analysis, closure and safety rules don't change.

Rewriting the framework

__objc_metadata is immediately before __LINKEDIT, and __LINKEDIT is the only segment that can safely move because it's addressed by file offsets. The rewrite replaces the segment contents, page-aligns the new size, moves __LINKEDIT down, rebases every load-command offset that points into it, and signs the binary ad hoc. Layouts it can't safely handle (fat binaries, a segment that isn't adjacent, metadata larger than the segment) are errors. Apps re-sign during their normal build.

Format compatibility

The CLI reads the format version from the framework and from the generated file, and refuses metadata newer than the framework can read. This matters today: the published macos-node-api and ios-node-api packages read format 1, while android-react-native writes format 2. A mismatch would otherwise exit at launch with Invalid metadata header version.

Categories

Testing on iOS exposed a generator bug. Category cursors are spelled with the category's own name, so a whitelist naming UIView dropped everything declared in UIViewGeometry, and UIView.frame became read-only. NativeScript/runtimes@cb26a2b exempts categories from the name filter. They only attach to classes that are kept, so this can't widen the class set.

Drawbacks

• Under-inclusion shows up at run time. The analysis is conservative, but a missing type only surfaces when that code path runs, so trimmed builds need real testing.
• Over-inclusion is coarse. Classes are kept whole, with all their members. Foundation is kept in full by default.
• Cross-platform bundles carry each other's names. Harmless, since names that match nothing cost nothing, but it's why trimming per platform matters.
• Tools must match the runtime. The analyzer and generator aren't in every package today, so paths are passed explicitly.
• Apple trimming needs Xcode's SDK on the machine running it, as metadata generation always has.
• Another step to learn, until a build integration makes it a config option.

Alternatives considered

Alternative	Why not
Only NS_METADATA_AUTO_FILTER / -PnsFilterMetadata	Tied to the Xcode and Gradle builds, so hosts with prebuilt frameworks get nothing. The command reuses this logic rather than replacing it
Hand-written native-api-usage.json alone	Accurate only while someone maintains it, and can't change a prebuilt framework. Kept as an input, not replaced
Analyze TypeScript source instead of the bundle	Misses plugins and framework code, and doesn't see tree-shaking
Runtime-only lazy loading of metadata	Helps memory and startup, but the bytes still ship. Lazy globals already gave part of this
Filter individual members	Larger savings, but much harder to keep correct across inheritance and protocols. Possible later
Separate tool per host	Duplicates the safety rules, which are the part that most needs to stay consistent

Adoption plan

1. nsh integration, as the first host and test bed (done).
2. Land the command in the CLI once this RFC settles.
3. Ship the tools with each runtime package, so --analyzer and --generator become optional.
4. @nativescript/macos-node-api: verify in a plain Node process and document it.
5. @nativescript/react-native: an install step for .nsmd resources, after runtimes#105.
6. Standard ns projects: a config option wired into prepare, off by default until it has run on real apps.

Unresolved questions

1. Tool discovery. Should the CLI find tools in the installed runtime package, and what's the contract each package must meet?
2. Default for release builds. Should this ever be on by default, and what evidence would justify it?
3. Format alignment. Published Node-API packages read format 1 and the generator writes format 2. Do we backport filtering to format 1, or move the packages first?
4. Blacklist conflicts. A blacklisted type that a kept API needs stays on Apple and fails the build on Android. Should they behave the same, and which way?
5. One analyzer or two. Apple uses a Rust analyzer and Android a JS harvester. Is converging them worth it?
6. Refuse or warn. Stopping on unbounded usage is the safe default. Should there be a way to accept a partial result, given that --keep exists?
7. Name. ns metadata trim, or something under ns build?

[edusperoni]

I believe this should be done after we settle #58

The bundler will then easily have enough information to get exactly the metadata you need. Then it should either generate the resulting metadata json before the native build or we can have something leveraging that that would generate the native-api-usage, allowing users to customize and add things as they need it. Having it all be a command with multiple arguments + keep + etc is shortsighted.

A few use cases:

1. multiple entrypoints
   1.1. Android uses this for services/extending application/etc
   1.2. workers
2. app sync/loading different bundles (needs more metadata than what was trimmed)

As is, I believe a command like ns metadata trim would just be bad DX overall and yet another thing people have to learn. If they do ns metadata trim and then decide to call something that there's no metadata for, they'll get a crash, whereas if you make it part of the build process, they can get a native rebuild once the metadata changes (based on bundler).

[edusperoni]

Also, see: #43