Install Visual Studio Tools for Apache Cordova

Article
07/01/2015

In Visual Studio 2013, the Cordova tools are released as a preview (CTP) version. Cordova tools will be released as part of Visual Studio 2015 and we recommend that you now use Visual Studio 2015 RC to develop apps using Visual Studio Tools for Apache Cordova. You can download Visual Studio from the Microsoft Download Center.

Take advantage of the easy-to-use installer to build cross-platform apps with Visual Studio and Apache Cordova. With the installer, you don’t have to identify the required SDKs, tools, and libraries (or which versions).

In this section:

Requirements
Get the tools
Install the tools
Install tools for iOS
Additional Tasks

Requirements

One of the following operating systems: Windows 7, Windows 8, Windows 8.1, or Windows Server 2012 R2.

Important

If you are using Windows 7, you can develop apps for Android and iOS, but not for Windows or Windows Phone.

To build apps for specific device platforms, there are a few additional requirements:

iOS and the iOS Simulator require a Mac computer capable of running Xcode 6 (Xcode 6 is recommended). For additional information and installation steps, see Install tools for iOS.

Tip

If you want to build iOS on a cloud service instead of Mac hardware, see Build and Simulate iOS in the Cloud.
Android emulators work best on computers that can run either Hyper-V or the Intel HAXM driver. See Run Your Apache Cordova App on Android.
Windows Phone emulators require a computer that can run Hyper-V. View the emulator's system requirements.

Get the tools

Get the Visual Studio Tools for Apache Cordova, which are installed as a separate extension in Visual Studio 2013 Update 4. Follow the steps in the next section to install the tools.

Important

Visual Studio 2015 RC is recommended for developing Apache Cordova apps. If you previously installed Visual Studio 2015 Preview or a Visual Studio 2015 CTP, you must first uninstall it using Control Panel, Programs and Features, before installing Visual Studio 2015 RC.

Install the tools

The installer for Visual Studio Tools for Apache Cordova includes a secondary installer to support Cordova app development. The secondary installer gives you the option to install the following third-party software. Most of these are open-source software required by specific platforms or by Apache Cordova.

Joyent Node.js enables Visual Studio to integrate with the Apache Cordova Command Line Interface (CLI) and Apache Ripple Emulator.
Git CLI is required only if you need to manually add Git URIs for specific Cordova plug-ins.
Google Chrome is required to run the Apache Ripple emulator for iOS and Android.
Apache Ant 1.8.0 or later is required for the Android build process.
32-bit Oracle Java JDK 7 is required for the Android build process.

Warning

64-bit Java is not supported.
Android SDK is required for the Android build process and Ripple.
Apple iTunes is required for deploying an app to an iOS device connected to your Windows PC.

To install Visual Studio Tools for Apache Cordova

Follow the instructions to install Visual Studio 2013 Update 4, and make sure you install the following optional features:
- Tools for Maintaining Store Apps for Windows 8
  
  Note
  
  If you are installing Visual Studio 2015 RC instead of Visual Studio 2013 Update 4 (we recommend Visual Studio 2015), the Cordova tools are installed as an optional component instead of a separate extension.
- Windows Phone 8.0 SDK.
  
  …
  
  Note
  
  You can add these features to an existing installation of Visual Studio 2013. In Control Panel, choose Programs and Features. Select Visual Studio 2013 from the list, and then choose Change. In the Visual Studio setup window, choose Modify. In the features list, select the optional features as shown in the illustration.
Run the installer that you found in Get the tools.
When prompted, allow the installer to install third-party software dependencies, or you can clear the software selections and manually install the dependencies you need later.

Important

If the third-party dependencies are already on your system or you choose to install them manually, you might have to update your system path. See install the dependencies manually.
Reboot your computer to make sure everything is installed correctly.
Open Visual Studio, choose Tools, then Extensions and Updates, and then Updates. If there is a Visual Studio update available for Visual Studio Tools for Apache Cordova, install it.

Note

The first time you build an app after installing the tools, Visual Studio will download and install the Cordova tools. As a result, the first build takes extra time to complete. Check the Output window to see progress. If you see an error Cannot find module [modulename], see Re-installing vs-tac.

Install tools for iOS

To build and run iOS apps on the iOS Simulator or on an iOS device using Visual Studio, you must install and configure the remote agent, vs-mda-remote, on a Mac computer that meets the requirements specified below. (Currently, iOS apps can't be built on Windows.) In Visual Studio on your PC, you must also configure the remote agent as described in this topic.

Note

For information on using cloud-hosted Mac services instead of a Mac, see Build and Simulate iOS in the Cloud. If you are running Windows on a Mac using virtualization technology, you can build and run iOS locally. For more information, see Build a Cordova app for iOS using Parallels.

Before you install the remote agent, make sure you have installed the Visual Studio Tools for Apache Cordova.

You can configure the agent to handle build requests and run the app on an iOS device or the iOS Simulator. To host the remote agent, the Mac computer must have the following installed:

Mac OS X Mavericks
Xcode 6
Xcode command-line tools (from Terminal app, use xcode-select --install)
Node.js
Git command line tools, if you are using a CLI from a Git repository.

If the CLI version is pointed to a Git location, Git is required to build the app for iOS.

You must also have the following:

An active iOS Developer Program account with Apple
An iOS provisioning profile configured in Xcode (download the provisioning profile and run the downloaded *.cer file)

Note

For detailed information, read the Maintaining Your Signing Identities and Certificates in the iOS Developer Library.
A signing identity configured in Xcode (choose XCode, Preferences)

To download and install the remote agent

From the Terminal app on your Mac, type:
```
sudo npm install -g vs-mda-remote --user=$USER
```
where $USER will be replaced by your user name on the Mac. When you run the command, you will be prompted to enter your password as well.

The global installation (-g) switch is recommended but not required.
If you have an older version of Node.js and npm, you may need to type the following commands before you start up the remote agent.
```
sudo npm cache clear
sudo chown -R `whoami` ~/.npm
```
This command ensures that permissions of the npm package cache in your home directory are correctly configured (newer versions of Node.js and npm will do this for you automatically.)

When you first start the remote agent (remotebuild), developer mode will be activated on your Mac. Homebrew will also be installed, along with ideviceinstaller and ios-webkit-debug-proxy, to allow automatically running apps on devices, and to allow debugging apps on devices and on the simulator.

Warning

To install Homebrew, you need sudo (administrator) access. If you need to install vs-mda-remote without sudo, you can install Homebrew manually in a usr/local location and add its bin folder to your path. For more information, see the Homebrew documentation. If you need to manually enable developer mode, type the following in the Terminal app: DevToolsSecurity –enable

If you updated your computer to a new version of Visual Studio, you must update to the current version of the remote agent as well.

To update the remote agent

Repeat the installation step from the previous section.

To start the remote agent

From the Terminal app on your Mac, type:
```
vs-mda-remote
```
This will start the agent with a default build directory of ~/remote-builds. Additional configurations options for the agent are described in Configure the remote agent.

The first time you start the agent, you will be provided with the required information to configure the agent in Visual Studio, including the host, the port, and the security PIN.

Important

vs-mda-remote has been designed to securely transfer build payloads to and from Visual Studio using a PIN.
If you intend to configure the remote agent in Visual Studio using the host name, ping the Mac using the host name to verify that it is reachable. Otherwise, you may need to use the IP address instead.

Before you can use the remote agent, you must specify the remote configuration in Visual Studio.

To configure the remote agent from Visual Studio

If the agent is not already running on your Mac, start the remote agent.
On your Mac, get the host name or IP address of your Mac.

You can get the IP address by using the ifconfig command.
On the Visual Studio menu bar, choose Tools, Options.
In the Options dialog box, open Tools for Apache Cordova, and then choose Remote Agent Configuration.
Set Enable remote iOS processing to True.
In the Host, Port, and Security PIN fields, type the values specified by the remote agent when you started it the first time. The host can be the name or IP address of your Mac. The default port is 3000.

Note

If you cannot ping the Mac using the host name, you may need to use the IP address.

When you click OK, Visual Studio will connect to the remote agent (the agent must be running to connect).

If you want to disable secure mode and enable simple HTTP-based connections, choose False as the Secure mode setting. Alternatively, type the following command in the Terminal app:
```
vs-mda-remote --secure false
```
If secure mode is disabled, you can leave the Security PIN field blank when configuring the agent in Visual Studio.

The security PIN is for one-time use. If you need to regenerate the security PIN, see Generate a new security PIN.

To stop the agent

From the Terminal app on your Mac, press Ctrl+C.

Additional Tasks

In some circumstances, additional steps may be required to update and configure the tools.

If you choose not to install one or more dependencies with Visual Studio Tools for Apache Cordova, you may need to install the dependencies manually
If you need to verify the path for a third-party dependency or if you have multiple versions of a dependency installed, see Override system environment variables
If you are running Visual Studio behind a proxy, see Configure tools to work with a proxy.
To use and configure the vs-mda-remote agent for building iOS apps, see the following:
If you see unexpected errors when trying to build the Blank App template, see Re-installing vs-tac.

Download the tools Get the Visual Studio Tools for Apache Cordova or learn more