Get Started with Windows

This guide will help you get started on setting up your very first React Native for Windows app.

Make sure you have installed all of the development dependencies.

For information around how to set up React Native, see the React Native Getting Started Guide.

Install React Native for Windows

Remember to call react-native init from the place you want your project directory to live.

To create TypeScript template, run npx react-native init

If you’ve installed react native globally in the past, via npm install -g react-native , and are having issues with the new instructions, try adding —ignore-existing to your npx command:
npx —ignore-existing react-native init

—template react-native@^0.64.0 instead.

Navigate into this newly created directory

Once your project has been initialized, React Native will have created a new sub directory where all your generated files live.

Install the Windows extension

Lastly, install the React Native for Windows packages.

The —overwrite flag copies a custom metro.config.js file. If you are starting a new app, this should have no impact. If you are adding Windows to your existing app and you have modified the metro.config.js file, please back up your changes, run the command and copy over to take effect.

Here are the options that react-native-windows-init takes:

Option	Input Type	Description
—help	boolean	Show help.
—version	string	The version of react-native-windows to use.
—namespace	string	The native project namespace.
—verbose	boolean	Enables logging.
—language	string [» cs «,» cpp «] [default: » cpp «]	Which language the app is written in.
—projectType	string [» app «,» lib «] [default: » app «]	The type of project to initialize.
—overwrite	boolean	Overwrite any existing files without prompting.
—useWinUI3	boolean	Targets WinUI 3.0 (Preview) instead of UWP XAML.
—no-telemetry	boolean	Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI

This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the —no-telemetry command line option. See the react-native-windows-init README for more details.

Running a React Native Windows App

Make sure a browser is launched and running before running a React Native Windows app. Also ensure your system meets all the requirements to build a Windows app as well.

Without Using Visual Studio

In your React Native Windows project directory, run:

A new Command Prompt window will open with the React packager as well as a react-native-windows app. This step may take a while during first run since it involves building the entire project and all dependencies. You can now start developing! :tada:

This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the —no-telemetry command line option. See the @react-native-windows/cli README for more details.

For a description of the options that run-windows offers, see run-windows usage.

Using Visual Studio

• From the root of the project directory, run the following script which will automatically link your app’s dependencies:
• Open the solution file in the application folder in Visual Studio (e.g., AwesomeProject/windows/AwesomeProject.sln if you used AwesomeProject as

)

Select the Debug configuration and the x64 platform from the combo box controls to the left of the Run button and underneath the Team and Tools menu item.

Run yarn start from your project directory, and wait for the React Native packager to report success.

Click the Run button to the right of the platform combo box control in VS, or select the Debug -> Start without Debugging menu item. You now see your new app and Chrome should have loaded http://localhost:8081/debugger-ui/ in a new tab. Press F12 or Ctrl+Shift+I in Chrome to open its Developer Tools. :tada:

• Open your applications folder in VS Code.
• Install the React Native Tools plugin for VS Code.
• Create a new file in the applications root directory, .vscode/launch.json and paste the following configuration:

• Press F5 or navigate to the debug menu (alternatively press Ctrl+Shift+D ) and in the Debug drop-down select «Debug Windows» and press the green arrow to run the application.

Authoring Native Modules

Building a standalone React Native Windows App

Follow these steps to build a version of your app that you can install or publish to the store. This version will package your bundle and assets into the APPX package so you don’t need to run Metro.

• Open the solution in Visual Studio
• Select the Release configuration from the Configuration Manager drop-down.
• Build the solution. You can now launch without first launching Metro.
• If you want to build an APPX package to share or publish, use the Project >Publish >Create App Packages. option.

Creating Universal Windows Apps with React Native

React.js is a popular JavaScript library for building reusable UI components. React Native takes all the great features of React, from the one-way binding and virtual DOM to debugging tools, and applies them to mobile app development on iOS and Android. With the React Native Universal Windows platform extension, you can now make your React Native applications run on the Universal Windows family of devices, including desktop, mobile, and Xbox, as well as Windows IoT, Surface Hub, and HoloLens.

This code story will walk you through the process of setting up a Universal Windows project for React Native, importing core Windows-specific modules to your JavaScript components, and running the app with Visual Studio.

Installing React Native for Windows

Installing the React Native Universal Windows platform extension is easy, whether you want to add the Windows platform to your existing app, or you want to start from scratch building an app just for Windows.

Adding React Native for Windows to Existing Projects

React Native developers are probably familiar with the react-native-cli, a tool for initializing React Native projects, deploying apps to devices, capturing JavaScript logs, upgrading versions, etc.

To start, make sure you have react-native-cli installed globally.

Once react-native-cli is installed, install the Windows plugin for React Native. The Windows plugin will expose new commands to the react-native-cli , specifically the react-native windows command, which you will use to initialize your project.

The windows command will do the following:

• Install react-native-windows from NPM
• Read the name of your project from package.json
• Use Yeoman to generate the Windows project files.

The react-native-cli plugin architecture searches your local package.json dependencies and devDependencies for modules that match rnpm-plugin-* , hence the —save-dev above.

Head to GitHub for more information on rnpm-plugin-windows .

Creating a React Native for Windows Project from Scratch

You have a few different options to create a React Native Universal Windows project from scratch. If your eventual intent is to also build apps for iOS and Android from the same code base, then the recommendation is first to use the existing tutorial to set up your React Native project, and then follow the steps above. For example:

Note: the react-native-windows NPM package is only compatible with the latest versions of react-native , from version 0.27 forward.

Otherwise, you can easily set yourself up with npm init .

Note: the default behavior for choosing the version of react-native-windows is to install the latest version if the package.json does not yet have a react-native dependency. Otherwise, if a react-native dependency already exists, the plugin will attempt to install a version of react-native-windows that matches the major and minor version of react-native .

The Windows plugin for React Native will automatically install the react-native and react peer dependencies for react-native-windows if they have not yet been installed.

React Native for Windows Project Structure

There are a few boilerplate files that get generated for the Universal Windows App. The important ones include:

• index.windows.js is the entry point to your React application.
• windows/myapp.sln is where you should start to launch your app and debug native code.
• windows/myapp/MainPage.cs is where you can tweak the native bridge settings, like available modules and components.

Here’s the full output:

We ship the core C# library for React Native as source on NPM. Having direct access to the source will help with debugging and making small tweaks where necessary. As long as the core ships as source, third party modules will also need to follow suit (although their dependencies may be binary). We’ll be working with the React Native community on react-native link support to make dependency management as simple as possible. Instructions for how to link dependencies are available on GitHub.

Building and Extending Apps for the Windows Platform.

The core components and modules for React Native are imported as follows:

Currently, the same goes for Android- and iOS-specific modules:

Since Windows is a plugin to the framework, core modules specific to Windows are imported from react-native-windows :

So, a typical imports section of a React component with a mixture of core and Windows-specific modules will look like:

There is a list of the core modules available on React Native for Windows on GitHub.

There are multiple ways to add conditional behavior to your apps based on the platform. One way that you might already recognize is the use of the *.platform.js pattern, that is, index.[android|ios|windows].js . The node-haste dependency graph will choose the filename that matches the active platform choice, and fallback to the filename without any platform indicator, if available. For example, if you have files MyComponent.windows.js and MyComponent.js , node-haste will choose MyComponent.js for Android and iOS and MyComponent.windows.js for Windows.

Another way is to use conditional logic inside a component, as demonstrated in the simple component below.

Facebook has a very good article on cross-platform design with React Native at makeitopen.com.

Running the Universal Windows App

There are a few options for running your React Native Universal Windows app. The easiest way is to use the run-windows command that is enabled once react-native-windows is installed in your project:

This command will deploy your app to the desktop. There are other options and flags you can use to deploy to emulators and devices, which you can read about using react-native run-windows —help . The easiest way, however, to deploy to other devices such as emulators and Xbox is to launch the app in Visual Studio. After initializing the project, open the Visual Studio solution at ./windows/myapp.sln in Visual Studio 2015 (Community Edition is supported). From Visual Studio, choose which platform you want to build for (x86, x64, or ARM), choose the target you want to deploy to, and press F5.

The instructions for running React Native UWP apps, both from Visual Studio and from the CLI, will be evolving on GitHub.

If you have any problems getting started with building or running your React Windows application, reach out on Discord or open an issue. We look forward to hearing your feedback and reviewing your contributions!

React native windows app

React Native for Windows

Build native Windows apps with React.

See the official React Native website for an introduction to React Native.

React Native is a framework developed by Facebook that enables you to build world-class application experiences on native platforms using a consistent developer experience based on JavaScript and React. The focus of React Native is on developer efficiency across all the platforms you care about — learn once, write anywhere.

This repository adds support for the Windows 10 SDK, which allows you to build apps for all devices supported by Windows 10 including PCs, tablets, 2-in-1s, Xbox, Mixed reality devices etc.

Status and roadmap

Check out our blog if you’d like to stay up to date on the status of React Native for Windows and check out current and past roadmaps. We will post all new releases, updates and general news about the project there.

You can run React Native Windows apps only on devices supported by the Windows 10 SDK.

For a full and detailed list of the system requirements and how to set up your development platform, see our System Requirements documentation on our website.

See the Getting Started Guide on our React Native for Windows + macOS website to build your first React Native for Windows app.

Search the existing issues and try to make sure your problem doesn’t already exist before opening a new issue. If your issue doesn’t exist yet, try to make sure you provide as much information as possible to us so we can help you sooner. It’s helpful if you include information like:

• The version of Windows, React Native, React Native Windows extension, and device family (i.e., mobile, desktop, Xbox, etc.) where you ran into the issue.
• A stack trace and reduced repro case when possible.
• Ensure the appropriate template is used when filing your issue(s).

See Contributing guidelines for how to setup your fork of the repo and start a PR to contribute to React Native for Windows.

good first issue and help wanted are great starting points for PRs.

React Native already has great documentation and we’re working to ensure the React Native Windows is part of that documentation story.

React Native for Windows has it’s own separate documentation site where Windows and macOS specific information, like API docs and blog updates live.

• Using the CLI in the Getting Started guide will set you up with a sample React Native for Windows app that you can begin editing right away.
• If you’re looking for sample code, just browse the RNTester folder in the GitHub web UI

The React Native Windows extension, including modifications to the original Facebook source code, and all newly contributed code is provided under the MIT License. Portions of the React Native Windows extension derived from React Native are copyright Facebook.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

About

A framework for building native Windows apps with React.