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 Visual Studio on Windows.

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|windows

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 Windows ​

Chrome DevTools ​

Start a debug session on the local machine with:

ns debug windows

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

# NativeScript Debugger started #
To start debugging, open the following URL in Chrome:
devtools://devtools/bundled/inspector.html?ws=127.0.0.1:43000

Open the printed URL in Google Chrome to attach to the debugger session. The inspector listens on port 43000 (iOS uses 41000 and Android 42000), or the next free port if 43000 is taken.

Alternatively open chrome://inspect in Chrome, click Configure..., add 127.0.0.1:43000, and select the app from the Remote Target list. Any other client that speaks the Chrome DevTools Protocol can connect to the same address.

The same options as on the other platforms are supported:

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

ns run windows doesn't start the inspector, use ns debug windows instead.

The debugger, console, sources, CPU profiling and memory snapshots are provided by V8's inspector. Network requests made with @nativescript/core HTTP APIs are shown in the Network tab.

Console output ​

ns run windows and ns debug windows stream the app's console output to your terminal. The output is also written to:

• the debugger output (visible in the Visual Studio Output window or DebugView)
• %LOCALAPPDATA%\Packages\<PackageFamilyName>\LocalState\console.log

Crash logs ​

When the app crashes, the runtime writes diagnostic files to the app's LocalState folder (%LOCALAPPDATA%\Packages\<PackageFamilyName>\LocalState\):

• nativescript-crash.log — unhandled JavaScript and XAML errors (also streamed to the terminal)
• nativescript-panic.log — internal runtime errors
• nativescript-veh.log — fatal native exceptions

In debug builds, an uncaught JavaScript error during startup shows a NativeScript Runtime Error dialog with the error details and the option to copy them or restart the app.

Some XAML errors terminate the process immediately (for example error 0xC000027B) without reaching these logs. In that case check Event Viewer › Windows Logs › Application, or capture a crash dump with ProcDump. See Troubleshooting › Windows.

Debugging native code with Visual Studio ​

To debug native (C#, C++ or WinRT) code, run the app with ns run windows, then in Visual Studio use Debug › Attach to Process..., select your app's process, and choose the Managed and/or Native code types. You can also open the generated host project in platforms/windows/<ProjectName>/ in Visual Studio to browse and set breakpoints in its code.