Windows Platform Guide
This guide shows how to set up your SDK development environment to build and deploy Cordova apps for Windows 8, Windows 8.1, Windows Phone 8.1, and Windows 10 Universal App Platform. It shows how to use either shell tools to generate and build apps, or the cross-platform Cordova CLI discussed in The Command-Line Interface. (See the Overview for a comparison of these development options.) This section also shows how to modify Cordova apps within Visual Studio. Regardless of which approach you take, you need to install the Visual Studio SDK, as described below.
See Upgrading Windows 8 for information on how to upgrade existing Windows 8 Cordova projects.
Window Phone 8 (wp8) stays as a separate platform, see Windows Phone 8 Platform Guide for details.
Cordova WebViews running on Windows rely on Internet Explorer 10 (Windows 8.0) and Internet Explorer 11 (Windows 8.1 and Windows Phone 8.1) as their rendering engine, so as a practical matter you can use IE's powerful debugger to test any web content that doesn't invoke Cordova APIs. The Windows Phone Developer Blog provides helpful guidance on how to support IE along with comparable WebKit browsers.
Requirements and Support
To develop apps for Windows platform you need:
A Windows 8.1, 32 or 64-bit machine (Home, Pro, or Enterprise editions) with minimum 4 GB of RAM.
Windows 8.0, 8.1 or 10, 32 or 64-bit Home, Pro, or Enterprise editions, along with Visual Studio 2012 Express or Visual Studio 2013. Visual Studio 2015 is not able to build Windows 8.0 apps.
To develop apps for Windows 8.0 and 8.1 (including Windows Phone 8.1):
Windows 8.1 or Windows 10, 32 or 64-bit Home, Pro, or Enterprise editions, along with Visual Studio 2013 Express or higher. An evaluation version of Windows 8.1 Enterprise is available from the Microsoft Developer Network.
For the Windows Phone emulators, Windows 8.1 (x64) Professional edition or higher, and a processor that supports Client Hyper-V and Second Level Address Translation (SLAT). An evaluation version of Windows 8.1 Enterprise is available from the Microsoft Developer Network.
Visual Studio 2013 for Windows (Express or higher).
To develop apps for Windows 10:
- Windows 8.1 or Windows 10 Technical Preview 2, 32- or 64-bit, along with Visual Studio 2015 RC or higher.
App compatibility is determined by the OS that the app targeted. Apps are forwardly-compatible but not backwardly-compatible, so an app targeting Windows 8.1 cannot run on 8.0, but an app built for 8.0 can run on 8.1.
Follow the instructions at windowsstore.com to submit the app to Windows Store.
To develop Cordova apps for Windows, you may use a PC running Windows, but you may also develop on a Mac, either by running a virtual machine environment or by using Boot Camp to dual-boot a Windows 8.1 partition. Consult these resources to set up the required Windows development environment on a Mac:
Using Cordova Shell Tools
If you want to use Cordova's Windows-centered shell tools in conjunction with the SDK, you have two basic options:
Access them locally from project code generated by the CLI. They are available in the
platforms/windows/directory after you add the
windowsplatform as described below.
Download them from a separate distribution at cordova.apache.org. The Cordova distribution contains separate archives for each platform. Be sure to expand the appropriate archive,
cordova-windowsin this case, within an empty directory. The relevant batch utilities are available in
package/bindirectory. (Consult the README file if necessary for more detailed directions.)
These shell tools allow you to create, build, and run Windows apps. For information on the additional command-line interface that enables plugin features across all platforms, see Using Plugman to Manage Plugins.
Install the SDK
Install any edition of Visual Studio matching the version requirements listed above.
For Windows 10, the Visual Studio installer has an option to install tools to build Universal Windows Apps. You must ensure that this option is selected when installing to install the required SDK.
Create a New Project
At this point, to create a new project you can choose between the
cross-platform CLI tool described in The Command-Line Interface, or
the set of Windows-specific shell tools.
The CLI approach below generates an app named HelloWorld
within a new
hello project directory:
> cordova create hello com.example.hello HelloWorld > cd hello > cordova platform add windows
Here's the corresponding lower-level shell-tool approach:
C:\path\to\cordova-windows\package\bin\create.bat C:\path\to\new\hello com.example.hello HelloWorld
This project targets Windows 8.1 as the default target OS. You can choose to target 8.0 or 10.0 (see "Configure target Windows version" below) for all builds, or you target specific a particular version during each build.
Build the Project
If you are using the CLI in development, the project directory's
www directory contains the source files. Run either of
these within the project directory to rebuild the app:
> cordova build > cordova build windows # do not rebuild other platforms > cordova build windows --debug # generates debugging information > cordova build windows --release # signs the apps for release
Here's the corresponding lower-level shell-tool approach:
C:\path\to\project\cordova\build.bat --debug C:\path\to\project\cordova\build.bat --release
clean command helps flush out directories in preparation for the
Configure target Windows version
build command produces two packages: Windows 8.0 and Windows Phone 8.1.
To upgrade Windows package to version 8.1 the following configuration setting must be
added to configuration file (
<preference name="windows-target-version" value="8.1" />
Once you add this setting
build command will start producing Windows 8.1
and Windows Phone 8.1 packages.
The --appx parameter
You may decide that you want to build a particular version of your application targeting a particular OS (for example, you might have set that you want to target Windows 10, but you want to build for Windows Phone 8.1). To do this, you can use the
> cordova build windows -- --appx=8.1-phone
The build system will ignore the preference set in config.xml for the target Windows version and strictly build a package for Windows Phone 8.1.
Valid values for the
--appx flag are
uap (for Windows 10 Universal Apps). These options also apply to the
cordova run command.
Considerations for target Windows version
Windows 10 supports a new "Remote" mode for Cordova apps (and HTML apps in general). This mode enables apps much more freedom with respect to use of DOM manipulation and common web patterns such as the use of inline script, but does so by reducing the set of capabilities your app may use when submitted to the public Windows Store. For more information about Windows 10 and Remote Mode, look at the Cordova for Windows 10 documentation.
When using Remote Mode, developers are encouraged to apply a Content Security Policy (CSP) to their application to prevent script injection attacks.
Deploy the app
To deploy Windows package:
> cordova run windows -- --win # explicitly specify Windows as deployment target > cordova run windows # `run` uses Windows package by default
To deploy Windows Phone package:
> cordova run windows -- --phone # deploy app to Windows Phone 8.1 emulator > cordova run windows --device -- --phone # deploy app to connected device
You can use cordova run windows --list to see all available targets and
cordova run windows --target=target_name -- --phone to run application on a
specific device or emulator
cordova run windows --target="Emulator 8.1 720P 4.7 inch" -- --phone).
You can also use cordova run --help to see additional build and run options.
Open the Project in the SDK and Deploy the App
Once you build a Cordova app as described above, you can open it with
Visual Studio. The various
build commands generate a Visual Studio
Solution (.sln) file. Open the file in the File Explorer to modify
the project within Visual Studio:
CordovaApp component displays within the solution, and its
directory contains the web-based source code, including the
index.html home page:
The controls below Visual Studio's main menu allow you to test or deploy the app:
With Local Machine selected, press the green arrow to install the app on the same machine running Visual Studio. Once you do so, the app appears in Windows 8's app listings:
Each time you rebuild the app, the version available in the interface is refreshed.
Once available in the app listings, holding down the CTRL key while selecting the app allows you to pin it to the main screen:
Note that if you open the app within a virtual machine environment, you may need to click in the corners or along the sides of the windows to switch apps or access additional functionality:
Alternately, choose the Simulator deployment option to view the app as if it were running on a tablet device:
Unlike desktop deployment, this option allows you to simulate the tablet's orientation, location, and vary its network settings.
NOTE: Consult the Overview for advice on how to use Cordova's command-line tools or the SDK in your workflow. The Cordova CLI relies on cross-platform source code that routinely overwrites the platform-specific files used by the SDK. If you want to use the SDK to modify the project, use the lower-level shell tools as an alternative to the CLI.
Windows requires an app manifest capability declaration in order to support
toast notifications. When using the
plugin, or any other plugin that is attempting to use toast notifications,
add the following preference to your config.xml to enable it to publish
<preference name="WindowsToastCapable" value="true" />
This preference sets the corresponding flag in your app manifest. Plugins should do the work necessary to configure the appearance of the displayed notifications.