Skip to main content

ReactInstanceSettings

New Architecture​

Kind: class

Provides settings to create a React instance.

Properties​

BundleAppId​

string BundleAppId

The name of the app passed to the packager server via the 'app' query parameter. This is useful when bundling multiple applications from the same packager instance. If no value is set, the parameter will not be passed.

BundleRootPath​

string BundleRootPath

Default value: ms-appx:///Bundle/

Base path used for the location of the bundle. This can be an ms-appx:// or ms-appdata:// URI (if the app is UWP or packaged using MSIX), a filesystem path, or a URI pointing at an embedded resource. Examples:

  • ms-appx:///Bundle - locates the bundle in the MSIX package. See URI schemes for other UWP/MSIX valid URI formats.
  • C:\\foo\\bar - locates the bundle in the local filesystem. Note UWP app file access permissions.
  • resource://moduleName - locates the bundle as an embedded RCDATA resource in moduleName. Specify the resource ID in JavaScriptBundleFile.
  • resource:// - locates the bundle as an embedded RCDATA resource in the running process's module. Specify the resource ID in JavaScriptBundleFile.

ByteCodeFileUri​

string ByteCodeFileUri

Set this to a location the application has write access to in order for bytecode to be successfully cached. See EnableByteCodeCaching. Note that currently the byte code generation is not implemented for UWP applications.

DebugBundlePath​

string DebugBundlePath

When loading from a bundle server (such as metro), this is the path that will be requested from the server. If this is not provided, the value of JavaScriptBundleFile is used.

DebuggerBreakOnNextLine​

bool DebuggerBreakOnNextLine

For direct debugging, controls whether to break on the next line of JavaScript that is executed. This can help debug issues hit early in the JavaScript bundle load. Note: this is not supported with the Chakra JS engine which is the currently used JavaScript engine. As a workaround you could add the debugger keyword in the beginning of the bundle.

DebuggerPort​

uint16_t DebuggerPort

Default value: 9229

When UseDirectDebugger is enabled, this controls the port that the JavaScript engine debugger will run on.

DebuggerRuntimeName​

string DebuggerRuntimeName

Name to associate with the JavaScript runtime when debugging. This name will show up in the list of JavaScript runtimes to attach to in edge://inspect or other debuggers

EnableByteCodeCaching​

bool EnableByteCodeCaching

Default value: false

For JS engines that support bytecode generation, this controls if bytecode should be generated when a JavaScript bundle is first loaded. Subsequent runs of the application should be faster as the JavaScript will be loaded from bytecode instead of the raw JavaScript. ByteCodeFileUri must be set to a location the application has write access to in order for the bytecode to be successfully cached. Note that currently the byte code generation is not implemented for UWP applications.

EnableDefaultCrashHandler​

bool EnableDefaultCrashHandler

Default value: false

Enables the default unhandled exception handler that logs additional information into a text file for Windows Error Reporting.

EnableDeveloperMenu​

bool EnableDeveloperMenu

Deprecated: This property has been replaced by UseDeveloperSupport. In version 0.63 both properties will do the same thing. It will be removed in a future version.

This controls whether various developer experience features are available for this instance. In particular the developer menu, and the default RedBox experience.

EnableJITCompilation​

bool EnableJITCompilation

Default value: true

Flag controlling whether the JavaScript engine uses JIT compilation.

JSIEngineOverride​

JSIEngine JSIEngineOverride

Default value: JSIEngine.Chakra

The JSIEngine override to be used with the React instance. In order for the override to work, Microsoft.ReactNative must be compiled with support of that engine. This override will be ignored when UseWebDebugger is set to true, since the browser must use its own engine to debug correctly.

JavaScriptBundleFile​

string JavaScriptBundleFile

Default value: index.windows

The name of the JavaScript bundle file to load. This should be a relative path from BundleRootPath. The .bundle extension will be appended to the end, when looking for the bundle file. If using an embedded RCDATA resource, this identifies the resource ID that stores the bundle. See BundleRootPath.

NativeLogger​

LogHandler NativeLogger

Function that will be hooked into the JavaScript instance as global.nativeLoggingHook. This allows native hooks for JavaScript's console implementation. If this is not set then logs will print output to the native debug output in debug builds, and no-op in release builds.

Notifications​

readonly IReactNotificationService Notifications

Gets a IReactNotificationService to send notifications between components and the application. Use IReactContext.Notifications to access this IReactNotificationService from native components or view managers.

PackageProviders​

readonly IVector<IReactPackageProvider> PackageProviders

Gets a list of IReactPackageProvider. Add an implementation of IReactPackageProvider to this list to define additional native modules and custom view managers to be included in the React instance. Auto-linking automatically adds IReactPackageProvider to the application's PackageProviders.

Properties​

readonly IReactPropertyBag Properties

Gets a IReactPropertyBag to share values between components and the application. Use IReactContext.Properties to access this IReactPropertyBag from native components and view managers.

RedBoxHandler​

IRedBoxHandler RedBoxHandler

Provides an extension point to allow custom error handling within the react instance. See IRedBoxHandler for more information.

RequestDevBundle​

bool RequestDevBundle

When querying the bundle server for a bundle, should it request the dev bundle or release bundle.

RequestInlineSourceMap​

bool RequestInlineSourceMap

Default value: true

When using UseFastRefresh, UseLiveReload, or UseWebDebugger this controls whether the bundler should include inline source maps.If set, the bundler will include the source maps inline (this will improve debugging experience, but for very large bundles it could have a significant performance hit)

SourceBundleHost​

string SourceBundleHost

Default value: localhost

When using UseFastRefresh, UseLiveReload, or UseWebDebugger this is the server hostname that will be used to load the bundle from.

SourceBundlePort​

uint16_t SourceBundlePort

Default value: 8081

When using UseFastRefresh, UseLiveReload, or UseWebDebugger this is the server port that will be used to load the bundle from.

UIDispatcher​

IReactDispatcher UIDispatcher

Control the main UI dispatcher to be used by the React instance. If the ReactInstanceSettings object is initially created on a UI thread, then this will default to that thread. The value provided here will be available to native modules and view managers using IReactContext.UIDispatcher

UseDeveloperSupport​

bool UseDeveloperSupport

This controls whether various developer experience features are available for this instance. In particular, it enables the developer menu, the default RedBox and LogBox experience.

UseDirectDebugger​

bool UseDirectDebugger

Enables debugging in the JavaScript engine (if supported). For Chakra this enables debugging of the JS runtime directly within the app using Visual Studio -> Attach to process (Script)

UseFastRefresh​

bool UseFastRefresh

Controls whether the instance triggers the hot module reload logic when it first loads the instance. Most edits should be visible within a second or two without the instance having to reload. Non-compatible changes still cause full reloads. See Fast Refresh for more information on Fast Refresh.

UseLiveReload​

bool UseLiveReload

Deprecated: For general use this has been replaced by UseFastRefresh.

Enables live reload to load the source bundle from the React Native packager. When the file is saved, the packager will trigger reloading.

UseWebDebugger​

bool UseWebDebugger

Deprecated: Debugging should be done using DirectDebugging rather than WebDebugger. Web debugging changes the app behavior and will be removed in a future version.

Controls whether the instance JavaScript runs in a remote environment such as within a browser. By default, this is using a browser navigated to http://localhost:8081/debugger-ui served by Metro/Haul. Debugging will start as soon as the react native instance is loaded.

Constructors​

ReactInstanceSettings​

ReactInstanceSettings()

Events​

InstanceCreated​

The InstanceCreated (unresolved reference) event is triggered right after the React Native instance is created.

It is triggered on the JSDispatcher thread before any other JSDispatcher work items. No JavaScript code is loaded in the JavaScript engine yet. The InstanceCreatedEventArgs.Context property on the event arguments provides access to the instance context.

Note that the InstanceCreated (unresolved reference) event is triggered in response to the 'InstanceCreated' notification raised in the 'ReactNative.InstanceSettings' namespace. Consider using Notifications (unresolved reference) to handle the notification in a dispatcher different from the JSDispatcher.

Type: EventHandler<InstanceCreatedEventArgs>

InstanceDestroyed​

The InstanceDestroyed (unresolved reference) event is triggered when React Native instance is destroyed.

It is triggered on the JSDispatcher thread as the last work item before it shuts down. No new JSDispatcher work can be executed after that. The InstanceDestroyedEventArgs.Context property on the event arguments provides access to the instance context.

Note that the InstanceDestroyed (unresolved reference) event is triggered in response to the 'InstanceDestroyed' notification raised in the 'ReactNative.InstanceSettings' namespace. Consider using Notifications (unresolved reference) to handle the notification in a dispatcher different from the JSDispatcher.

Type: EventHandler<InstanceDestroyedEventArgs>

InstanceLoaded​

The InstanceLoaded (unresolved reference) event is triggered when React Native instance has finished loading the JavaScript bundle.

It is triggered on the JSDispatcher thread. If there were errors, then the InstanceLoadedEventArgs.Failed property on the event arguments will be true. The error types include:

  • JavaScript syntax errors.
  • Global JavaScript exceptions thrown.

The InstanceLoadedEventArgs.Context property on the event arguments provides access to the instance context.

Note that the InstanceLoaded (unresolved reference) event is triggered in response to the 'InstanceLoaded' notification raised in the 'ReactNative.InstanceSettings' namespace. Consider using Notifications (unresolved reference) to handle the notification in a dispatcher different from the JSDispatcher.

Type: EventHandler<InstanceLoadedEventArgs>

Referenced by​

Old Architecture​

Kind: class

Provides settings to create a React instance.

Properties​

BundleAppId​

string BundleAppId

The name of the app passed to the packager server via the 'app' query parameter. This is useful when bundling multiple applications from the same packager instance. If no value is set, the parameter will not be passed.

BundleRootPath​

string BundleRootPath

Default value: ms-appx:///Bundle/

Base path used for the location of the bundle. This can be an ms-appx:// or ms-appdata:// URI (if the app is UWP or packaged using MSIX), a filesystem path, or a URI pointing at an embedded resource. Examples:

  • ms-appx:///Bundle - locates the bundle in the MSIX package. See URI schemes for other UWP/MSIX valid URI formats.
  • C:\\foo\\bar - locates the bundle in the local filesystem. Note UWP app file access permissions.
  • resource://moduleName - locates the bundle as an embedded RCDATA resource in moduleName. Specify the resource ID in JavaScriptBundleFile.
  • resource:// - locates the bundle as an embedded RCDATA resource in the running process's module. Specify the resource ID in JavaScriptBundleFile.

ByteCodeFileUri​

string ByteCodeFileUri

Set this to a location the application has write access to in order for bytecode to be successfully cached. See EnableByteCodeCaching. Note that currently the byte code generation is not implemented for UWP applications.

DebugBundlePath​

string DebugBundlePath

When loading from a bundle server (such as metro), this is the path that will be requested from the server. If this is not provided, the value of JavaScriptBundleFile is used.

DebuggerBreakOnNextLine​

bool DebuggerBreakOnNextLine

For direct debugging, controls whether to break on the next line of JavaScript that is executed. This can help debug issues hit early in the JavaScript bundle load. Note: this is not supported with the Chakra JS engine which is the currently used JavaScript engine. As a workaround you could add the debugger keyword in the beginning of the bundle.

DebuggerPort​

uint16_t DebuggerPort

Default value: 9229

When UseDirectDebugger is enabled, this controls the port that the JavaScript engine debugger will run on.

DebuggerRuntimeName​

string DebuggerRuntimeName

Name to associate with the JavaScript runtime when debugging. This name will show up in the list of JavaScript runtimes to attach to in edge://inspect or other debuggers

EnableByteCodeCaching​

bool EnableByteCodeCaching

Default value: false

For JS engines that support bytecode generation, this controls if bytecode should be generated when a JavaScript bundle is first loaded. Subsequent runs of the application should be faster as the JavaScript will be loaded from bytecode instead of the raw JavaScript. ByteCodeFileUri must be set to a location the application has write access to in order for the bytecode to be successfully cached. Note that currently the byte code generation is not implemented for UWP applications.

EnableDefaultCrashHandler​

bool EnableDefaultCrashHandler

Default value: false

Enables the default unhandled exception handler that logs additional information into a text file for Windows Error Reporting.

EnableDeveloperMenu​

bool EnableDeveloperMenu

Deprecated: This property has been replaced by UseDeveloperSupport. In version 0.63 both properties will do the same thing. It will be removed in a future version.

This controls whether various developer experience features are available for this instance. In particular the developer menu, and the default RedBox experience.

EnableJITCompilation​

bool EnableJITCompilation

Default value: true

Flag controlling whether the JavaScript engine uses JIT compilation.

JSIEngineOverride​

JSIEngine JSIEngineOverride

Default value: JSIEngine.Chakra

The JSIEngine override to be used with the React instance. In order for the override to work, Microsoft.ReactNative must be compiled with support of that engine. This override will be ignored when UseWebDebugger is set to true, since the browser must use its own engine to debug correctly.

JavaScriptBundleFile​

string JavaScriptBundleFile

Default value: index.windows

The name of the JavaScript bundle file to load. This should be a relative path from BundleRootPath. The .bundle extension will be appended to the end, when looking for the bundle file. If using an embedded RCDATA resource, this identifies the resource ID that stores the bundle. See BundleRootPath.

NativeLogger​

LogHandler NativeLogger

Function that will be hooked into the JavaScript instance as global.nativeLoggingHook. This allows native hooks for JavaScript's console implementation. If this is not set then logs will print output to the native debug output in debug builds, and no-op in release builds.

Notifications​

readonly IReactNotificationService Notifications

Gets a IReactNotificationService to send notifications between components and the application. Use IReactContext.Notifications to access this IReactNotificationService from native components or view managers.

PackageProviders​

readonly IVector<IReactPackageProvider> PackageProviders

Gets a list of IReactPackageProvider. Add an implementation of IReactPackageProvider to this list to define additional native modules and custom view managers to be included in the React instance. Auto-linking automatically adds IReactPackageProvider to the application's PackageProviders.

Properties​

readonly IReactPropertyBag Properties

Gets a IReactPropertyBag to share values between components and the application. Use IReactContext.Properties to access this IReactPropertyBag from native components and view managers.

RedBoxHandler​

IRedBoxHandler RedBoxHandler

Provides an extension point to allow custom error handling within the react instance. See IRedBoxHandler for more information.

RequestDevBundle​

bool RequestDevBundle

When querying the bundle server for a bundle, should it request the dev bundle or release bundle.

RequestInlineSourceMap​

bool RequestInlineSourceMap

Default value: true

When using UseFastRefresh, UseLiveReload, or UseWebDebugger this controls whether the bundler should include inline source maps.If set, the bundler will include the source maps inline (this will improve debugging experience, but for very large bundles it could have a significant performance hit)

SourceBundleHost​

string SourceBundleHost

Default value: localhost

When using UseFastRefresh, UseLiveReload, or UseWebDebugger this is the server hostname that will be used to load the bundle from.

SourceBundlePort​

uint16_t SourceBundlePort

Default value: 8081

When using UseFastRefresh, UseLiveReload, or UseWebDebugger this is the server port that will be used to load the bundle from.

UIDispatcher​

IReactDispatcher UIDispatcher

Control the main UI dispatcher to be used by the React instance. If the ReactInstanceSettings object is initially created on a UI thread, then this will default to that thread. The value provided here will be available to native modules and view managers using IReactContext.UIDispatcher

UseDeveloperSupport​

bool UseDeveloperSupport

This controls whether various developer experience features are available for this instance. In particular, it enables the developer menu, the default RedBox and LogBox experience.

UseDirectDebugger​

bool UseDirectDebugger

Enables debugging in the JavaScript engine (if supported). For Chakra this enables debugging of the JS runtime directly within the app using Visual Studio -> Attach to process (Script)

UseFastRefresh​

bool UseFastRefresh

Controls whether the instance triggers the hot module reload logic when it first loads the instance. Most edits should be visible within a second or two without the instance having to reload. Non-compatible changes still cause full reloads. See Fast Refresh for more information on Fast Refresh.

UseLiveReload​

bool UseLiveReload

Deprecated: For general use this has been replaced by UseFastRefresh.

Enables live reload to load the source bundle from the React Native packager. When the file is saved, the packager will trigger reloading.

UseWebDebugger​

bool UseWebDebugger

Deprecated: Debugging should be done using DirectDebugging rather than WebDebugger. Web debugging changes the app behavior and will be removed in a future version.

Controls whether the instance JavaScript runs in a remote environment such as within a browser. By default, this is using a browser navigated to http://localhost:8081/debugger-ui served by Metro/Haul. Debugging will start as soon as the react native instance is loaded.

Constructors​

ReactInstanceSettings​

ReactInstanceSettings()

Events​

InstanceCreated​

The InstanceCreated (unresolved reference) event is triggered right after the React Native instance is created.

It is triggered on the JSDispatcher thread before any other JSDispatcher work items. No JavaScript code is loaded in the JavaScript engine yet. The InstanceCreatedEventArgs.Context property on the event arguments provides access to the instance context.

Note that the InstanceCreated (unresolved reference) event is triggered in response to the 'InstanceCreated' notification raised in the 'ReactNative.InstanceSettings' namespace. Consider using Notifications (unresolved reference) to handle the notification in a dispatcher different from the JSDispatcher.

Type: EventHandler<InstanceCreatedEventArgs>

InstanceDestroyed​

The InstanceDestroyed (unresolved reference) event is triggered when React Native instance is destroyed.

It is triggered on the JSDispatcher thread as the last work item before it shuts down. No new JSDispatcher work can be executed after that. The InstanceDestroyedEventArgs.Context property on the event arguments provides access to the instance context.

Note that the InstanceDestroyed (unresolved reference) event is triggered in response to the 'InstanceDestroyed' notification raised in the 'ReactNative.InstanceSettings' namespace. Consider using Notifications (unresolved reference) to handle the notification in a dispatcher different from the JSDispatcher.

Type: EventHandler<InstanceDestroyedEventArgs>

InstanceLoaded​

The InstanceLoaded (unresolved reference) event is triggered when React Native instance has finished loading the JavaScript bundle.

It is triggered on the JSDispatcher thread. If there were errors, then the InstanceLoadedEventArgs.Failed property on the event arguments will be true. The error types include:

  • JavaScript syntax errors.
  • Global JavaScript exceptions thrown.

The InstanceLoadedEventArgs.Context property on the event arguments provides access to the instance context.

Note that the InstanceLoaded (unresolved reference) event is triggered in response to the 'InstanceLoaded' notification raised in the 'ReactNative.InstanceSettings' namespace. Consider using Notifications (unresolved reference) to handle the notification in a dispatcher different from the JSDispatcher.

Type: EventHandler<InstanceLoadedEventArgs>

Referenced by​