Create Your First Apache Cordova App

Article
05/22/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.

An app built using Visual Studio Tools for Apache Cordova uses Cordova to access native APIs by using web technologies like HTML and CSS. By reducing or eliminating the need for native code, apps work across multiple devices.

Some tasks are common to most Cordova apps. These include:

Create a Cordova project
Build and run the default "Hello" app
Choose a third-party JavaScript framework
Build a UI
Add native features (plugins)
Add connected services
Add platform-specific resources
Test, package, and publish

Create a Cordova project

Before you can create a new project, make sure that you’ve met all system requirements and installed the Visual Studio Tools for Apache Cordova extension for Visual Studio. For more information, see Install Visual Studio Tools for Apache Cordova.

To create a new project

Open Visual Studio. On the menu bar, choose File, New, Project.
In the New Project dialog box, under Templates, choose JavaScript, Apache Cordova Apps, and then choose the Blank App template.

Note

A Blank App template for TypeScript is under TypeScript, Apache Cordova (the complete ToDoList tutorial uses JavaScript.)
Choose Browse to find a location for the project.
Give the app a name and then choose OK.

Note

If you intend to go through the complete tutorial by creating the ToDoList sample app, name the app AngularJSToDo.

Visual Studio creates the new project and opens Solution Explorer in the right pane.

Important

The project structure in Visual Studio 2015 RC is updated to support third-party CLIs, and to match the Cordova project structure. Visual Studio 2013 uses the deprecated project structure. We recommend that you create Cordova apps using Visual Studio 2015.

The new Cordova project includes four top-level folders:

merges is used to add platform-specific code. For more information, see Configure Your App Built with Visual Studio Tools for Apache Cordova.
- By default, the Blank App template includes commonly used platform-specific code for Windows and Android devices in the merges folder. (platformOverrides.js is used to specify the platform file.)
- For Android devices, a .js file is included to provide support for the JavaScript Function.prototype.bind() function on Android 2.3 devices.
- For Windows and Windows Phone 8.1, a winstore-jscompat.js file is included in the merges\windows folder to enable support for a variety of JavaScript libraries. For more information, see the JavaScript Dynamic Content shim for Windows Store apps project site.
plugins is used for Apache Cordova plugins that provide access to native device features.
res is used for platform-specific visual assets (icons and splash screens), signing certificates, and (if needed) platform-specific configuration files. For more information, see Configure Your App Built with Visual Studio Tools for Apache Cordova.
www folder, which is used for your app code.

The www folder contains several more folders:
- css contains basic CSS style sheets that are included with the blank template.
- images is the suggested location for images for your app.
- scripts is the default location for all JavaScript or TypeScript files.

In addition to CSS and JavaScript files, the new project also includes several more files:

config.xml contains configuration settings for your app. You can open this file from Solution Explorer in the configuration designer, an interface for config.xml, or you can edit it directly by selecting View Code from the shortcut menu for the file.
taco.json stores project metadata that enables Visual Studio to build on non-Windows operating systems like a Mac.
www\index.html is the default home screen for your app.
Project_Readme.html contains links to useful information.

For in-depth information on the Cordova build process in Visual Studio and on the Visual Studio project structure, see Deploy and Run your App.

Build and run the default "Hello" app

After you create a project using the default Blank App template, run a quick test to verify your installation and setup. For this initial test, run the default "Hello" app (the unmodified Blank App template) on either Windows or one of the Apache Ripple emulators, which have minimal setup requirements. If you prefer to test your app on another target, see the following topics: Run Your Apache Cordova App on Android, Configure the Visual Studio Tools for Apache Cordova, and Run Your Apache Cordova App on Windows Phone.

To build and run the default "Hello" app

Choose Windows-x64, Windows-x86, or Android from the Solution Platforms list.

The following illustration shows the Android platform.

If the Solution Platforms list isn’t showing, choose Solution Platforms from the Add/Remove Buttons list, and then choose your platform (Windows-x64, Windows-x86, or Android).
If you chose the Android platform, choose one of the Apache Ripple emulators, as shown here.

If you are using Visual Studio 2015 and have Hyper-V enabled on your machine you can run the app on the Visual Studio Emulator for Android (select an option such as VS Emulator Android Phone).

If you chose a Windows platform, you can run the app on the default deployment target, Local Machine.
Press F5 to start debugging, or Shift+F5 to start without debugging.

Here’s what the default app looks like in one of the Ripple emulators.

Tip

If you are running on a Ripple emulator and you get an error that indicates you need to install a new version of the Android SDK, use the Android SDK Manager to install it. On Windows, SDK Manager.exe is in C:\Program Files (x86)\Android\android-sdk.

If you see an error such as Cannot find module [modulename], see Re-installing vs-tac. If you experience other problems, see Known Issues and the FAQ.
Press Shift + F5 to stop debugging.

Next steps:

To continue this tutorial by creating the ToDoList sample app using AngularJS, see Create the ToDoList Sample App. This sample app includes information on using Azure Mobile Services and Bing Maps services. (The same ToDoList sample app is available for WinJS and Backbone.)

Note

To download ToDoList samples for Visual Studio 2013, see the deprecated samples on github…
Look at other types of samples in Samples, Tutorials, and Videos.
It can be challenging to create an app with a well-designed UI that works cross-platform. In many cases, you will want to use a third party CSS and JavaScript framework to get started. Starter templates for UI include Ionic SideMenu Starter Template and the WinJS Navigation template. Visual Studio 2013 versions of these samples are here and here.

Choose a third-party JavaScript framework

Typically, when building a Cordova app, you’ll also want to include a third-party JavaScript framework to make application development easier or to follow best practices for designing apps. You're not limited to just one framework! (Nor is one required. These frameworks are not part of Cordova.)

Third-party JavaScript frameworks may include a variety of features and design characteristics, such as:

Model-View-Controller (MVC) design patterns to help separate application concerns. AngularJS and Backbone are just two popular examples of this.
UI controls and styles. A UI framework (or library) typically includes specific controls, such as a grid control, and sometimes CSS style sheets. For more info, see Build a UI.
Navigation model. Frameworks like AngularJS and open source WinJS, and other frameworks provide a single-page navigation model to help enable app-like behavior.

Build a UI

Cordova apps run in a WebView control on all platforms except Windows and Windows Phone 8.1, so they will tend to look more like web apps. When planning a UX for customers, it is important to ask a couple of questions:

Do you want your app to look the same on different platforms?

A UI framework typically provides a branded experience and is intended to look the same across platforms. A few examples of popular UI frameworks include Ionic and Bootstrap.

For a sample that uses Ionic, see the Ionic SideMenu Starter Template.
If you want a native look-and-feel, are you targeting a particular platform more than others?

Some UI frameworks may resemble a particular platform's look-and-feel, such as iOS. If you are aiming for a native look-and-feel for each platform, development cost will be higher and a native look-and-feel may be difficult to achieve.

It is important to follow the design guidelines for particular platforms to make sure that your app can pass the review process. Apps don't necessarily need to look native to get approved for an app store, but they should behave more like an app than a web page. For more information. see Get Your Cordova App Approved by the App Stores.

For a sample that uses Ionic, see the Ionic SideMenu Starter Template. For a sample that uses open-source WinJS, see WinJS Navigation template.

If your UI is relatively simple, or if you have the development resources on hand, you can create your own UI using best practices for cross-platform CSS, such as using CSS3 Flexbox and @media queries. There are many web resources that provide information about this. For a sample that shows some of these techniques, see AngularJS Master-Detail Sample.

A few things to keep in mind if you build your own UI:

If you target Android 4.4 or later (Chromium-based browser), Windows, or Windows Phone, support for current CSS standards and other web technologies is better. See caniuse.com for specific information on supported features.
If you target iOS or Android versions before 4.4, the browser is WebKit-based. (The Ripple Emulator, which uses the installed version of Chrome, behaves more like Android 4.4.) Some WebKit browser behavior is different. For example, WebKit browsers don't provide consistent support for vw and vh units, which are useful when designing a responsive UI.

Tip

Use the merges folder in your project to handle platform differences that can't be coded in a more generic fashion.

Add native features (plugins)

One of the most important features that Cordova provides is support for plugins that enable access to native features, such as geolocation and battery. Using a plugin, you can program to a generic JavaScript API. Core plugins typically support all the main platforms, while third-party plugins may require more investigation. If plugin support is not available, you may need to customize an existing plugin or write your own, which will require native code.

For more info, see Manage Plugins for Apps Built with Visual Studio Tools for Apache Cordova

Add connected services

If your app is using Azure or Office365 services, see Add Connected Services to Your App Built with Visual Studio Tools for Apache Cordova. A core plugin for Azure Mobile Services is available in the Config Designer in Visual Studio.

For information on adding the Azure services in the task list sample app for Visual Studio Tools for Apache Cordova (AngularJS version), see Create the ToDoList Sample App.

To get started creating apps using Azure or O365 services with Cordova, see the following articles and blog posts.

Try it now (get an Azure account)
Cordova Sample App with O365 Discovery Service and the Files API
Cordova Sample App using O365 Outlook Services and Ionic
Push Notifications to Cordova Apps with Microsoft Azure (MSDN Magazine)
Writing…Data Services (Blog posts include articles on using Azure with Cordova)

Add platform-specific resources

Platform-specific resources, like splash screens and store icons, are required to get apps approved for download from app stores. The res folder in your project contains these resources. You can also use the res folder to add custom configuration files. For more info, see Configure Your App Built with Visual Studio Tools for Apache Cordova.

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

Share via