Debugging

There are multiple ways to debug issues in your apps, starting with the simplest form using console.logs. For more complex issues, you may need to use an actual debugger, like Chrome DevTools, XCode developer tools and instruments, the Android Studio developer tools or GDB on Linux.

Console ​

The quickest way to inspect state is to log values to the console. NativeScript supports console methods like log, info, warn, error, trace, dir, time and timeEnd.

The time(label: string) method starts a new timer and is very useful to measure how long something took. To stop the timer, call timeEnd with the same label, and the execution time will be printed to the console.

console.log('General message')
console.info('Informational message')
console.warn('Warning')
console.error('Error')

// also prints a stack trace to the current line
console.trace('Trace message')

// prints all members of someVariable
console.dir(someVariable)

// starts a timer
console.time('myLabel')
await someLongTask()
// ends a timer and prints elapsed time
console.timeEnd('myLabel')

Additional Resources:

• MDN Console documentation

Debugging with Chrome DevTools ​

To start a Chrome debugging session, run your app in debug mode:

ns debug android|ios|linux

The ns debug command builds and deploys the app on a connected device or emulator, in case you have multiple devices available you will need to pick one from a list, or pass in the --device <id> from ns devices.

Once the app starts, a URL is printed to the console

Setting up debugger proxy...
Press Ctrl + C to terminate, or disconnect.

Opened localhost 41000
To start debugging, open the following URL in Chrome:
devtools://devtools/bundled/inspector.html?ws=localhost:41000

Visit the printed URL (devtools://devtools/bundled/inspector.html?ws=localhost:41000) in Google Chrome to attach to the debugger session.

You can customize the ns debug command using any of the following options:

• --debug-brk - stops execution at the first JavaScript line until either the debugger frontend connects or a 30 seconds timeout elapses.
• --start - attaches the debug tools to an already deployed and running app.
• --emulator - specifies that you want to debug the app in an emulator.
• --timeout - number of seconds that the NativeScript CLI will wait for the debugger to boot. Default is 90 seconds.
• --no-watch - changes in your code will not be livesynced.
• --clean - forces rebuilding the native application.

If you are new to JavaScript debugging, we recommend reading the following resources from Chrome Developers to get familiar with the basics:

• Debugging JavaScript

Supported Chrome DevTools features ​

Debugging with VS Code ​

VS Code uses the same protocol as the Chrome DevTools, in order to start a debugging session in VS Code you need to install the NativeScript extension for VS Code.

Debugging with XCode ​

If you need to debug parts of the native stack instead of the JavaScript part of your app, you can use the XCode debugger as well as all the XCode Instruments to find issues in your app such as memory leaks, hangs, CPU heavy tasks and more.

To start, prepare the iOS app:

ns prepare ios

This compiles your app source, creates the platforms/ios folder (if it doesn't exist yet). You can pass any of the flags you would normally pass to ns run.

Next, open the platforms/ios/<project-name>.xcworkspace in XCode, either through the XCode browse menu, or from the command line:

open platforms/ios/<project-name>.xcworkspace

Select a target device or simulator, and then run the app via the "Play" button. Navigate to the native code in the XCode project, and place breakpoints, when the app hits those it will pause execution and you will be able to step through the native code.

If a crash occurs, the XCode debugger will stop the execution and print a thread dump and a location where the app is crashing. In many cases the stack will point to symbol identifiers like 0x1088f3960 which usually means the source code is not availble for the offending code (could be an external pre-compiled library). If the crash occurs in the NativeScript runtime itself, you can attach the runtime source to be able to see the exact line that is crashing, and also place breakpoints and step throuhg the runtime code with your application. A detailed guide can be found in the NativeScript iOS Runtime Readme.

Since NativeScript utilises a standard XCode project structure, you can do everything you would typically do with a pure iOS application:

• debug view hiearchy
• memory dumps/graphs
• XCode Instruments: leaks, cpu profiling, hangs and more
• ...and more

Additional Resources:

• Apple XCode: Debugging iOS apps
• Apple XCode: Setting breakpoints
• Attaching the NativeScript runtime to an app

Debugging with Android Studio ​

If you need to debug parts of the native stack instead of the JavaScript part of your app, you can use Android Studio to find issues in your app.

To start, prepare the Android app:

ns prepare android

This compiles your app source, creates the platforms/android folder (if it doesn't exist yet). You can pass any of the flags you would normally pass to ns run.

Next, open the platforms/android folder in Android Studio, through the Android Studio browse menu.

studio platforms/android

Since NativeScript follows a standard gradle/android application structure, you can do everything you would typically do with a pure Android application:

• debug view hieararchy
• memory dumps/graphs
• cpu profiling
• ...and more

Additional Resources:

• Android Studio: Layout Inspector
• Android Studio: view Logcat logs
• Androud Studio: Debug your app

Debugging on Linux ​

Chrome DevTools ​

Start a debug session on the local machine with:

ns debug linux

The command builds and launches the app with the V8 inspector enabled. Once the inspector is listening, a URL is printed to the console:

To start debugging, open the following URL in Chrome:
devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229/<id>

Open the printed URL in Google Chrome or Chromium to attach to the debugger session. The inspector listens on port 9229, which can be changed with the NS_LINUX_INSPECTOR_PORT environment variable.

The app also shows up in chrome://inspect, and other clients that speak the Chrome DevTools Protocol, such as the VS Code JavaScript debugger, can attach to 127.0.0.1:9229.

The same options as on the other platforms are supported:

• --debug-brk - pauses on the first line of JavaScript until the debugger connects.
• --start - attaches to an app that is already running with the debugger enabled (started with ns debug linux), without restarting it.
• --timeout - number of seconds the CLI waits for the inspector to start. Default is 90 seconds.

ns run linux doesn't start the inspector, use ns debug linux instead. The debugger is only available with the default @nativescript/linux (V8) runtime, and it is turned off in release builds unless the inspector fuse is enabled.

The debugger, console, sources, CPU profiling and memory snapshots are provided by V8's inspector. In CPU profiles, time spent in C functions is shown under the C function's name. Network requests made with @nativescript/core HTTP APIs are shown in the Network tab.

Console output ​

ns run linux and ns debug linux stream the app's standard output and standard error (including console calls and uncaught errors) to your terminal. Run the CLI with --log trace to also see when the app starts and exits, with its exit code or signal.

An app started from the desktop's app launcher writes its output wherever the desktop session sends it, usually the systemd journal (journalctl --user -f).

Debugging native code with GDB ​

To debug C code (your own native code, GTK or the runtime), attach GDB to the running app:

ns run linux
# in another terminal
gdb -p $(pgrep -n <ProjectName>)

Native code in debug builds is compiled with -O0 -g, so GDB can show its sources and variables.

To debug GTK warnings and critical messages, set G_DEBUG=fatal-criticals in the environment before running the CLI. The app then stops at the first critical message, and GDB shows where it came from.