Improve this


Using Cordova, you can easily create a new Onsen UI app, or turn an existing Onsen UI website into an Android or iOS app.

Setting up and maintaining the Cordova build process can be time-consuming. The Onsen UI team has created a tool called Monaca, which can build apps for you automatically, ready to upload to the app stores. It makes the build process simple so you can concentrate on developing your app.

Basic Cordova App

If you have never used Cordova before, the best way to get started is to follow the official Create your first Cordova app guide. This will guide you through the basic Cordova concepts and how to get up and running.

If you are somewhat familiar with Cordova, and already have your computer set up for building Android or iOS apps (that is, you have Android Studio or Xcode correctly set up), then these commands will quickly set up a blank Cordova app for you. You can substitute android with ios in any of these commands.

npm install -g cordova
cordova create sampleapp io.onsen.sampleapp "Onsen UI Sample App"
cd sampleapp
cordova platform add android
cordova emulate android

If you want to build iOS apps, but don’t have a Mac, take a look at Monaca, built by the Onsen UI team.

Adding Onsen UI

Now that you have a basic Cordova app set up, getting Onsen UI working is simple. Remove all of the files inside Cordova’s www folder to get rid of all the sample code. If you have an existing Onsen UI website, all you need to do is put all the code inside www, and re-run the app as before.

If this your first time using Onsen UI, follow our usual Getting Started guide. Any files which the guide tells you to create should be placed inside www. To run the app, simply run cordova emulate android as above.

Differences to a website

There are some differences between a website and an app that you should keep in mind.

Not always online

Though users assume a website will break when they are offline, they do not expect the same from an app. You should ensure that your app works well offline, or at least fails gracefully. Do not use the CDN links for Onsen UI in your app. Instead, store the Onsen UI .js and .css files somewhere in the www folder. This is important to make sure the app works offline.

Add cordova.js script

To access most of Cordova’s advanced features, you need access to its Javascript functions. To do this, simply add this tag inside your index.html. You do not need to have an actual cordova.js file. When your app is built, Cordova automatically adds it for you.

<script src="cordova.js"></script>
Use relative paths

On Android, your app’s base path is not / as you might expect, but rather file:///android_asset/www/. Make sure you always use relative file paths to avoid any problems with this. For example, if you have an image located at www/img/1.jpg, both the tags below would work on a website, but only one would load correctly in your Cordova app.

Advanced Cordova

Here are some further useful links from the official Cordova docs: