NativeScript application wide runtime settings (updated 5.2)

NativeScript Switch

On thing most people are probably not aware of is that the Android runtimes has a large number of knobs and switches to customize certain behavior of the engine.   I will try and list out all the current switches and knobs that you can use.   iOS now has one switch.

First of all the settings go into the /app/package.json   If you open up the default package json you probably will see:

{   
    "android": {      
        "v8Flags": "--expose_gc"    
   },    
   "main": "app.js",
   "name": "tns-template-hello-world",
   "version": "5.2.0"
}

That "android" key is where everything goes for Android specific settings.   The default setting that comes in the files is "v8Flags": "--expose_gc" this one is rather critical in that this enabled the runtime to call gc from JavaScript.   Now, there is quite a few v8Flags you can use; most the time they aren't needed but if you need to tune the v8 engine; you can add more flags into this string.  I even list a few in this post.   Let me warn you again; DO NOT remove the "--expose_gc".   You will cause your app to crash when something attempts to call the GC from code.

As of version 5.2; there is a "ios" key called "jscFlags" option that is now available. My recommendation while building/testing your app is to add the key "ios": { "jscFlags":"--validateOptions=1" } The jscFlags has items that can be used to tweak the JavaScript core engine. You can find more flags here.

Ok, so here is the complete list of settings you can change in the Android section:

SettingDefaultMin VersionDescription
gcThrottleTime03.xAllows you to throttle
how frequently JS GC
triggers native GC
See:
Memory Management
memoryCheckInterval03.xHow frequently to check
memory usage
See:
Memory Management
freeMemoryRatio0.03.xRation of memory before a GC is ran (works with
memoryCheckInterval)
See:
Memory Management
markingModefull3.xSwitches which type of GC engine to use.  "none" will enable a different engine which doesn't do
marking.  Typically faster
for Angular apps
handleTimeZoneChangesfalse4.1True will enable the
ability for a time zone
change in the settings to
effect the NS app.
maxLogcatObjectSize10244.0How many lines of text a
console output will log.
forceLogfalse4.0True will enable logging
in release mode
suppressCallJSMethodExceptionfalse5.1True will suppress the
boolean type conversion error from null that could randomly occur and crash the application.
codeCachefalse2.xTrue - Enables code
caching in the v8 engine.
v8Flags--expose_gc1.xTunes the v8 engine
heapSnapshotBlob""2.x(Believe to be unused
now)
heapSnapshotScript""2.x(Believe to be unused
now)
snapshot.blob""2.x(Believe to be unused
now)
profilerOutputDirKey""2.x(Believe to be unused
now)
profiling""2.x(Believe to be unused
now)

IOS Level Flags:

SettingDefaultMin VersionDescription
gcThrottleTime05.2Allows you to throttle
how frequently JS GC
triggers native GC
See: Custom Flags
memoryCheckInterval05.2How frequently to check memory usage
See: Custom Flags
freeMemoryRatio0.05.2Ration of memory before a GC is ran (works with
memoryCheckInterval)
See: Custom Flags
jscFlags""5.2Tunes the JavaScriptCore engine. Valid Flags

Top Level Global Flags:

SettingDefaultMin VersionDescription
discardUncaughtJsExceptionsfalse4.2True - will disable
crashing on JS errors, will
log any issues to console.

Recommended changes:
discardUncaughtJsExceptions: "true" - This will keep the app from crashing on certain types of errors; this should be enabled for release mode! Some developers might find it more productive to have this enabled while coding to eliminate application crashes. Please note you MUST pay attention to the console if you enable this during development; because most JS errors that would crash out; will now be just logged to the console.

suppressCallJSMethodExceptions: "true" - This will keep the app from crashing on the boolean conversion issue that can occasionally occur.  This is not to say the app might have some other issue later; but this will eliminate a stupid (imho) crash reason.

markingMode: "none" - This will enable the experimental GC engine, this will help incredibly with Angular based apps. Please note it "might" cause more crashing errors if a plugin forgot to hold a reference to something it needed later. However with the above discardUncaughtJsExceptions enabled; those errors won't crash the app.

Late Breaking news; in 4.2 they actually moved "discardUncaughtJsExceptions" to the top level of the package; the reason why is because shortly after they added the support to Android; the support was added to iOS.  So now this flag controls both iOS and Android, so it no longer belongs just in the "android" block.

So in your package json would look like this if you used my recommended settings:

{
   "android": {
       "v8Flags": "--expose_gc",
       "markingMode": "none",
       "suppressCallKSMethodExceptions": "true"
    },
    "ios": {
        "jscFlags": "--validateOptions=1"
    },
    "discardUncaughtJsExceptions": "true",
    "main": "app.js",
    "name": "tns-template-hello-world",
    "version": "5.2.0"
}

3 comments

  1. Hey Nathan! Thanks for this interesting post! I was wondering whether below would then be the correct syntax to enable the flag. Also do you know how I can see the flags that are enable in runtime? Is there a away I can output them in the console?

    "v8Flags": "--expose_gc --discardUncaughtJsExceptions=true --markingMode=none"

    1. 1. You can manually read the package.json file yourself (using the file system api) and output it yourself.
      2. Flags are setup like so:
      "android" {
      "v8Flags": "--expose_gc",
      "discardUncaughtJsExceptions": "true"
      }

  2. Hi Nathan!

    Nevermind the question above. By chance I found an example of this in the nativescript-plugin-firebase demo app:

    "android": {
    "v8Flags": "--expose_gc",
    "discardUncaughtJsExceptions": true
    }

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.