Using Cordova CLI on Mac OS X to build iOS apps – updated 5/2016

This article gets you up to speed on how to integrate your HTML/CSS/JS app with PhoneGap/Cordova into an iOS app using a Mac and prepare it for App Store submission. Updated May 2016 for cordova 6.1.1. This article assumes you’ve already followed the steps on to:

Download Node.js
Add PATH statements to .profile

In this article, I am referencing Mac OS X Yosemite 10.10.5 and Xcode 6.3.1 on a Mac Mini. Cordova CLI 5.4.1 was installed. I am referencing “cordova” in the command-line interface, not “phonegap.” This project will not use the PhoneGap Build service. Any updates to these programs may affect the following instructions.

Download Apple’s latest OS  and Xcode if you haven’t already: 

Before you can install the app you create with PhoneGap on your device, you need to sign up as a Developer with Apple and go through the business documentation, Certificate Signing, Developer Certificate process, and more, all of which are detailed on Apple’s web site (, under Prepare for App Submission. Nevertheless, you can skip all those steps and still see your work in the the iOS Simulator included with Xcode — you just won’t be able to view the app in your device or App Store. Xcode is a free download you can download now, but the Developer status comes at $99 a year.

Although you can develop the HTML/CSS/JS portion of an iPhone app on a Windows machine, you’ll still need a Mac with Xcode to convert the code to the binary that is uploaded to the App Store. You need a Mac to make iPhone apps. (PhoneGap Build can create this binary for you from your files, but you still need a Mac to download and install certain certificate files.)

If you are new to creating apps for the App Store, you’ll want to peruse the App Store Review and other Guidelines to make sure your app meets the rules: You are strongly encouraged to make use of these documents before you start your project, lest you run afoul of Apple’s rules for what apps they will and will not allow in the App Store.

Cordova uses the command-line interface (CLI) to generate the files needed to start the project.  This article covers the creation of an app from CLI creation to upload binary to Apple.

Install Cordova CLI

1. With Node.js installed, open the Terminal app by clicking on it in the dock at bottom and issue the following command:

sudo npm install -g cordova

Or update your installation with this article:

Pay attention to the inconsistencies in the early PhoneGap documentation between the use of “phonegap” and “cordova” in the command line. For instance, the Command-line Interface online page uses “phonegap” while the InAppBrowser API online page uses “cordova.” They are not interchangeable when using CLI. As seen in the above command, we are asking to download “cordova.” So we would replace all instances of “phonegap” in the documentation with “cordova,” or the command will generate a “not found”-type error.

2. Give the root password and hit Enter. I got a series of ERR lines, ending with:

npm ERR! not ok code 0

I kept pasting the command and hitting Enter over and over until it completed (maybe three times). When successful, you should get a long list of lines beginning with “npm http,” then finally ending with a series of words containing the @ symbol and digit/dot pairings, terminating with your username at the end.

Create Cordova Project Files with CLI

1. Open a Finder window and select the folder you want to create your project’s folder inside of, such as /PhonegapApps
2. Open the Terminal app (click on its icon in the dock below, or click on the magnifying glass at top right and type in “terminal”), type cd and a space (for “change directory”), drag the selected folder to the Terminal screen, let go, click on the Terminal to select it, then hit Return. This will orient all commands to that folder.

For this project, all of your commands will always begin with “cordova.” Some online tutorials and PhoneGap documentation will tell you to use “phonegap;” in that case, change it to “cordova” and it should work fine.

3. Type the following in the terminal (“myApp” is this project’s app name — make your final app name less than 50 characters):

cordova create myApp

Basic files are generated in the /myApp folder.

4. Enter the new folder you created in Terminal with the cd (change directory) command:

cd myApp

5. CLI only downloaded the skeleton files needed for all platforms. Now you need to download the specific files for iOS:

cordova platform add ios

6. Open the /myApp/platforms folder to see a new folder, /ios.

7. Cordova included several files for a default one-screen app, complete with splashscreen and icon. To build the default Cordova app, type:

cordova build ios

8. After a time, the Xcode file was built and saved as: myApp/platforms/ios/HelloWorld.xcodeproj. Double-click on this file to open it in Xcode.

If you’re unfamiliar with the Xcode environment, read this paragraph. Otherwise, skip to the next one. When the Xcode screen comes on, look at the top and see a progress bar showing you the progress of the Open process. You’ll see a familiar Play triangle near the top left, a square Stop button, and to the right, the app name > iPhone 6s Plus (which is the clickable name of the simulator or device — if you click on it you’ll get a list of devices to choose from). Below that at left is a string of small icons. You should click on all of them to get an idea of what information they hold. (Don’t worry — you won’t break anything doing so!) The far left icon is a file folder icon; click on it to see the app directory. If the app files are not showing, there is a drop-down triangle to the left of an icon that represents your Xcode app. You can click on the small triangle to view the project contents.

9. Click on the Play triangle to view the project in the device simulator. The progress indicator at top keeps you apprised of the status. If you see a warning symbol with a number at right, it indicates potential problems. In that case, you may want to review this page to see if you missed something:

An iPhone screen appears, showing a white Apple logo on a black screen. If it is too large to fit in your screen, click on Window > Scale and an appropriate number, like 33%.  Below it is the progress bar. When it turns all white, you see the home screen. If the app does not launch automatically, then swipe the screen with your mouse until you see you app’s icon, then click on it.

If this is the default Cordova app, you’ll see a logo above the words APACHE CORDOVA with “Device is Ready” pulsing. This shows that the project is successfully showing the default index.html screen. Or if you had already replaced the default Cordova page with your own, your page would be seen.

10. Experiment. Try this with the iPhone simulator:
a) Click on the simulator then on Hardware > Device and choose among the available devices (they did not all work when I tried it).
b) Click on Window > Scale and resize the simulator (important if the entire simulator doesn’t fit in your window).
c) With Edit > Copy Screen you can grab it and possibly save for uploading as screenshots, if your screen and simulator sizes are large enough.
d) Click on Debug > Open System Log… to view the console output in separate windows. I personally did not find this information helpful.

11. In Xcode, click on the square Stop icon. The Simulator screen reverts to the device home screen with its icons. Click and hold on the app icon until it quivers, and an X appears. Confirm, then Hardware > Home. I recommend you delete the icon before creating a new build lest errors pile up. Sometimes the old code is not fully overwritten with a new cordova build process.

12. When you make changes to the app and open it in Xcode, you’ll want to make sure to click on your app name in the left column, then check in the middle pane under Deployment Info > Device Orientation that all relevant orientations have been checked. Also make sure that Devices shows iPhone, iPad, or Universal (for both device types).

Dec. 2015: There were many warnings in Xcode for CordovaLibs regarding stuff being deprecated in Cordova 3.9.2, including ‘whitelist’ code, even though my version is 5.4.1. Response: simply double-click on “Update to recommended…” then on Perform Changes. Ignore all other warnings.

Add the Whitelist Plugin

This has been deprecated for platform ios 3.9.2. We don’t include the Cordova whitelist plugin for iOS9.

However, Apple is incorporating strict security protocols for iOS9 and beyond with their new Application Transport Security. They require that our app’s external connections go only to servers incorporating HTTPS and other security measures. If your app already connects only to URLs that begin with HTTPS, you are probably good to go (though there is more to it than that — see the resource link following).

But what if your connections go to HTTP and not HTTPS? What if you don’t have access to the HTTP servers to upgrade them to HTTPS? Then you’ll need to opt out of ATS by allowing all connections (or all connections with some exceptions; see the resource below).

In Xcode, open /Resources/xxx-info.plist. Click on the arrow for App Transport Security  Settings. You’ll see that Allow Arbitrary Loads has been set to YES, which means your app is inherently insecure; it will allow all connections, including HTTP. I believe this was set because in our config.xml we have the line <access origin=“*” />, which allows all connections. (The info.plist is populated by the information in config.xml.)


Add the InAppBrowser Plugin

Cordova has the ability to add more features to the app via plugins. Cordova does not automatically install every feature and that keeps the code footprint down. Plugins:

We’ll incorporate the InAppBrowser (IAB) API. The IAB allows us to open external URL links from within the app. Some developers would prefer this over the default of leaving the app and opening a web browser, shutting down the web browser when done, then restarting the app again. The IAB opens the link in its own frame, with a Done button bringing the user back into the app.

We first download the IAB as a plugin using CLI.


Step I: download the plug-in

1. Still in your project’s folder in Terminal, type the add command:

cordova plugin add cordova-plugin-inappbrowser --save

2. Verify that the plugin is installed with the ls (list) command:

cordova plugin ls

Step II: add to the config.xml file


1. Open the myApp/www/config.xml file in a text editor (I use TextWrangler). Before Cordova CLI 5.0.0, we had to add lines like the following, but no more:

<feature name="InAppBrowser">
 <param name="ios-package" value="CDVInAppBrowser" />

The “–save” command in step 1 wrote the Cordova plugin lines for you.

The config.xml page is one of the reasons CLI (command line interface) is so good. We add our platform-related information to that page rather than opening up page after page in the different platform SDKs. The SDKs use the information in config.xml to prepare its own platform version.

2. While we’re on that page, change the other sections:

a. Change the version=”0.0.1″ to the correct version, like version=”1.0.0.″ When you fill out the fields for the app in the Apple dev site, you’ll put this in the version field, not “1.0,” or the app will not pass validation.
b. Change the <description> line.
c. Change the <author> section.
d. Make sure the “widget id” is the name of your app in reverse domain style, like com.developername.myApp. It needs to match up with the wording you put in the Apple dev site — the case must match or it will not pass validation.
e. Change the <name> to be what you want under the icon on the device’s home screen. 11 characters or fewer, because the name won’t wrap if it’s too long. This will also change the .xcodeproj filename. Spaces are permitted.


Issue found when creating this article

At first, the default project was called HelloCordova by Cordova in the config.xml <name></name> section, which I overwrote as myApp. Later I entered “My App” in <name></name> and later again changed it to “myApp” to investigated what changed in the build.

What happened in Xcode is that all those names are being remembered in the Xcode scheme – all except the current myApp. The HelloCordova and My App both default to Mac OS X in the scheme, and the only other selectable scheme is CordovaLib.

If you changed the <name> section and experience this problem, just remove the iOS platform with cordova platform rm ios in Terminal and add it back again with cordova platform add ios . That removed all the old data and started afresh. Note that this command will also remove all icons and splashscreen files too, and you’ll need to drag them back into Xcode the next time you do a cordova prepare ios or cordova build ios.

3. Make sure all pages using a Cordova API reference has the following in the <head> above all other .js references, and references cordova.js as being in the root folder. It needs to be on every page that uses a Cordova plugin. The lack of this part is one of the reasons why plugins fail:

 document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {

Cordova.js will be added to the /www folder whenever you do a cordova prepare or cordova build. Make sure your pages access that folder for cordova.js.

The entire top part of the page in my case is:

<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta content="minimum-scale=1.0, width=device-width, maximum-scale=1.0, user-scalable=no" name="viewport">
<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: 'unsafe-eval'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; media-src *">
App Name

< script type="text/javascript" charset="utf-8" src="cordova.js"></script> 
< script>
// Wait for Cordova to load
document.addEventListener("deviceready", onDeviceReady, false);
// Cordova is ready
function onDeviceReady() {

(WordPress no longer retains formatted script tags in the document that contain opening and closing angle brackets, but I was able to include them by inserting a space after an opening bracket like this: < script. If you copy/paste the above, make sure you remove that space from two locations.)

Note the reference to cordova.js. This line must point to the www/ folder. If the page is in www/chapters/here.html, then you would add ../ for each folder away from www/; so in this case the line would read:

< script type="text/javascript" charset="utf-8" src="../cordova.js"></script>

If you have questions about the <meta http-equiv=”Content-Security-Policy” lines, please read these pages:

4. Now let’s test it. Open PhoneGap’s /myApp/www/index.html page and replace portions with the following lines in these inAppBrowser instructions:

5. Save the page. Whenever you make a change to a project’s files, you must do the following steps before opening the project in Xcode. In Terminal:

cordova prepare ios

6. Double-click on the/myApp/platforms/ios/myApp.xcodeproj file to open it in Xcode, then Project > Clean. That purges the old files and makes sure you have the current build. Then you Build and Run in the sim of your choice.

Add the Dialogs Plugin (optional)

I don’t like the default JavaScript alerts. The title of the alert gives the filename of the page, like index.html, rather than something nicer (or left empty). The Dialogs plugin gives us a few more options to customize the alert. See the resources for more options than the sample I’m giving below.

1. Still in your project’s folder in Terminal, type the add command for the plugin:

cordova plugin add cordova-plugin-dialogs --save

2. [removed]

3. Enter the following alert code above the </head> line. The function confirmation() is the code for the alert that the button will pop up; function alertDismissed() is the code that will execute when the user taps the Done button in the alert:

function alertDismissed() {
 // do something, like redirect to an external page, or do nothing'', '_blank');
function confirmation() {
 'Here is the alert!', // message
 alertDismissed, // callback (execute the above function of this name)
 'Your Title Here', // title
 'Done' // text of the close button

4. Add a button to execute the above confirmation() function. You can put this after the <body> line:

<button onclick="confirmation(); return false;" style="padding:1em; margin=1em; background-color:#ddd;">Pop the alert</button>

If you want more than one notification dialog on a page, then copy the above over and over for each dialog, but give each one different function and callback names to keep them unique for each one containing its own purpose.

Add FastClick.js (optional)

What does FastClick do? When you tap on a button or link, the system waits 300ms to see if you will tap again (a double-tap). If you don’t tap again within that 300ms period, then it assumes a single-tap and executes. FastClick removes this 300ms delay so your taps execute right away. All my buttons need single-tap only, so this is ideal. With FastClick.js, you’ll use “click” instead of “touchstart” for your links.


1. Go to the resource page above and right-click on the Minified link and save it to the hard drive with Save Link As… or similar, saving it as fastclick.js.
2. Copy it to your /myApp/www folder.
3. In all your pages where the file needs to be used, add above the </head> line:


Change /path/to/fastclick.js per page where needed so it points to the file.
4. In all your pages where the file needs to be used, before the function onDeviceReady() line, add:

window.addEventListener('load', function() {
}, false);

If onDeviceReady() is not used on the page, enclose the above in tags and put it above the </head> line. Now all your taps should result in a faster response time.
5. Sometimes you’ll need FastClick to ignore certain elements. You can do this easily by adding the needsclick class:

<a href="index.html" class="needsclick">Ignored by FastClick</a>

Please read the section below about the /Merges folder.

Add Your Icons


You may have noticed that the Cordova icon appears on your home screen on your test device. Let’s replace it with your own.

1. Create PNG icons in these sizes and filenames. I suggest making a more detailed 180×180 image and resize it down to 87×87, and a less-detailed image and use that for the smaller sizes. Test and see what works for you.

You can also use the free online service at to generate most of these sizes. Sizes not generated at this writing are the following:

icon-83.5.png, 84×84
icon-83.5@2x.png, 167×167
icon-72@2x.png, 144×144
icon-40@3x.png, 120×120
icon-50@2x.png, 100×100
icon-40@2x.png, 80x80px
icon-50.png, 50×50

You can open the icon-76@2x.png image in your image editor to make all the missing images under 167×167. I used Pixelmater on my Mac (Image > Image Size, then File > Export.)

iPhone (iOS 5,6 Spotlight) (iOS 5-8 Settings)

icon-small.png, 29×29
icon-small@2x.png, 58×58
icon-small@3x.png, 87×87

iPhone (iOS 7,8 Spotlight)

icon-40.png, 40x40px
icon-40@2x.png, 80x80px
icon-40@3x.png, 120×120

iPhone (iOS 5,6)

icon.png, 57×57
icon@2x.png, 114×114

iPhone (iOS 7,8)

icon-60@2x.png, 120×120
icon-60@3x.png, 180×180

iPad (iOS 5-8 Settings)

icon-small.png, 29×29
icon-small@2x.png, 58×58
icon-small@3x.png, 87×87

iPad (iOS 7,8 Spotlight)

icon-40.png, 40x40px
icon-40@2x.png, 80×80
icon-40@3x.png, 120×120

iPad (iOS 5,6 Spotlight)

icon-50.png, 50×50
icon-50@2x.png, 100×100

iPad (iOS 5,6)

icon-72.png, 72×72
icon-72@2x.png, 144×144

iPad (iOS 7,8)

icon-76.png, 76×76
icon-76@2x.png, 152×152

iPad Pro

icon-83.5.png, 84×84
icon-83.5@2x.png, 167×167


AppIcon.png, 120×120

2. Place them in a new folder, /myApp/res/icon/ios.

3. In config.xml, we add the following.

<platform name="ios"><!-- iPhone (iOS 5,6 Spotlight) (iOS 5-8 Settings) -->
<!-- iPad (iOS 5-8 Settings) -->
<icon src="res/icon/ios/icon-small.png" width="29" height="29" />
<icon src="res/icon/ios/icon-small@2x.png" width="58" height="58" />
<icon src="res/icon/ios/icon-small@3x.png" width="87" height="87" />
<!-- iPhone (iOS 7,8 Spotlight) -->
<icon src="res/icon/ios/icon-40@2x.png" width="80" height="80" />
<icon src="res/icon/ios/icon-40@3x.png" width="120" height="120" />
<!-- iPhone (iOS 5,6) -->
<icon src="res/icon/ios/icon.png" width="57" height="57" />
<icon src="res/icon/ios/icon@2x.png" width="114" height="114" />
<!-- iPhone (iOS 7,8) -->
<icon src="res/icon/ios/icon-60@2x.png" width="120" height="120" />
<icon src="res/icon/ios/icon-60@3x.png" width="180" height="180" />
<!-- iPad (iOS 7,8 Spotlight) -->
<icon src="res/icon/ios/icon-40.png" width="40" height="40" />
<icon src="res/icon/ios/icon-40@2x.png" width="80" height="80" />
<!-- iPad (iOS 5,6 Spotlight) -->
<icon src="res/icon/ios/icon-50.png" width="50" height="50" />
<icon src="res/icon/ios/icon-50@2x.png" width="100" height="100" />
<!-- iPad (iOS 5,6) -->
<icon src="res/icon/ios/icon-72.png" width="72" height="72" />
<icon src="res/icon/ios/icon-72@2x.png" width="144" height="144" />
<!-- iPad (iOS 7,8) -->
<icon src="res/icon/ios/icon-76.png" width="76" height="76" />
<icon src="res/icon/ios/icon-76@2x.png" width="152" height="152" />
<!-- iPad Pro -->
<icon src="res/icon/ios/icon-83.5.png" width="84" height="84" />
<icon src="res/icon/ios/icon-83.5@2x.png" width="167" height="167" />
<icon src="res/icon/ios/AppIcon.png" width="120" height="120" />

Remove any lines for sizes you are not providing. The list above matches exactly all the filenames listed above it.

4. Go to /platforms/ios/myApp/Resources/icons and delete all those standard Cordova icons. Replace them with your own. (The reason we make a myApp/res folder for our icons is in case we need to remove the ios platform and add it again. Removing the ios platform will also remove all those resources.)

6. We need to update the Assets Catalog for Xcode. In Terminal:

cordova prepare ios

7. Double-click on the /myApp/platforms/ios/myApp.xcodeproj file to open it in Xcode.

6. In Xcode: Product > Clean. If it is grayed out, then go to Product > New scheme… and call your new scheme myApp. Then it will show up in the scheme section. Now you can Product > Clean.

7. Verify your icons are recognized. Click on the folder icon at upper left, then on myApp, if the myApp file structure is not already showing. Click on /Resources, then on /icons. Click on a few of the icon filenames and watch as they appear to make sure they are yours.

If you do Product > Analyze and find the error: The AppIcon set “AppIcon” has an unassigned child., then click on the error message. The AppIcon set will appear at right with its icons. Scroll to the bottom to see the unassigned icon and note its name.

Now click on the folder icon above the app’s name in the left column, click on the Resources folder, open Images.xcassets, then click on AppIcon in the right column. Scroll to the bottom and click on the icon to select it. Now right-click on it to Remove Selected Items. Perform another Product > Clean then Product > Analyze to check for errors.

Add Your Launch Images (Splash Screens)


1. The splash screen (“launch screen” by Apple) is the image loaded before the app’s home screen appears. We add splash screen functionality with a plugin. In Terminal, making sure it starts within your myApp folder, add the plugin with:

cordova plugin add cordova-plugin-splashscreen --save

(To remove a plugin, type cordova plugin list and view the list of available plugins, then type cordova plugin rm and copy/paste the plugin line at the end ( like cordova plugin rm cordova-plugin-splashscreen), then hit Enter.)

2. Create new subfolders (“res” = resources): /myApp/res/screen/ios

3. Create your splash screens in the following sizes according to what devices you are supporting and add them to the above folder. I highly recommend using an image compression program on these files to keep the app size down, because all of the images will be ported over. Try

Launch images (portrait only shown):

iPhone Portrait, iOS 8
Retina HD 5.5 (1242 x 2208): Default-414w@3x.png
Retina HD 4.7 (750 x 1334): Default-375w@2x.png

iPhone Portrait, iOS 7,8

(320×480) Default~iphone.png
(640×960) Default-portrait@2x~iphone.png
(Retina4, 640×1136) Default-568h@2x~iphone.png

iPad Portrait, iOS 7,8
(768×1024) Default-portrait~ipad.png
(1536×2048) Default-portrait@2x~ipad.png

iPhone Portrait, iOS 5,6
(320×480) Default~iphone.png (mentioned above)
(640×960)Default-portrait@2x~iphone.png (mentioned above)
(Retina4, 640×1136) Default-568h@2x~iphone.png

iPad Portrait, iOS 5,6 (without status bar)
(Retina2x, 1536×2008) Default-portrait@2x~ipad.png

In my project, I am not using landscape images.

4. Add the following to our config.xml file above the </widget> line.

<platform name="ios">
<splash src="res/screen/ios/Default-375w@2x.png" width="750" height="1334"/>
<splash src="res/screen/ios/Default-414w@3x.png" width="1242" height="2208"/>
<splash src="res/screen/ios/Default-568h@2x~iphone.png" width="640" height="1136"/>
<splash src="res/screen/ios/Default-Portrait@2x~ipad.png" width="1536" height="2048"/>
<splash src="res/screen/ios/Default-portrait@2x~iphone.png" width="640" height="960"/>
<splash src="res/screen/ios/Default-Portrait~ipad.png" width="768" height="1024"/>
<splash src="res/screen/ios/Default~iphone.png" width="320" height="480"/>

Remove any lines for sizes you are not providing, such as the landscape images in my case.

4. Open your index.html page and change the document.addEventListener(“deviceready”, onDeviceReady, false); section so it reads like the following to turn off your splash screen when DeviceReady has fired:

// Wait for device API libraries to load 
document.addEventListener("deviceready", onDeviceReady, false); 
// device APIs are available

function onDeviceReady() {

5. [removed]

6. Go to /platforms/ios/myApp/Resources/splash and delete all those standard Cordova images. Replace them with your own from myApp/res/screen/ios. (The reason we make a myApp/res/screen/ios folder for our launch images is in case we need to remove the ios platform and add it again. Removing the ios platform will also remove all those resources.)

7. In Terminal:

cordova prepare ios

I got the errors:

cp: copyFileSync: could not write to dest file (code=ENOENT):/Users/.../platforms/ios/MyApp/Images.xcassets/AppIcon.appiconset/icon-50.png 

[more like this]

cp: copyFileSync: could not write to dest file (code=ENOENT):/Users/.../platforms/ios/MyApp/Images.xcassets/LaunchImage.launchimage/Default@2x~iphone.png 

[more like this]

To fix this, make sure you have your custom icons saved outside of your /platforms folder, and uninstall and reinstall the platform:

cordova platform rm ios

cordova platform add ios

Run cordova prepare ios again.

8. Shut down Xcode if it is open. Double-click on the /myApp/platforms/ios/myApp.xcodeproj file to open it in Xcode.

9. Product > Clean, then Product > Analyze. Hopefully, there are no errors. If there are, paste the error messages into search and check out the answers there.

Test Your Own App in the Simulator

Go ahead and replace the Cordova default files in /www with your own app project, if you have one. Remove the default folders CLI had created in the /www folder: /js, /css, /img. Put all your project assets there in /www.

1. In Terminal,

cordova prepare ios

2. Double-click on myApp.xcodeproj as before.

3. When Xcode opens, choose the scheme you want (which iPhone or iPad simulator you want to use). Watch carefully. Did you see your splash screen appear? Exit your app in the sim with Hardware > Home. Do you see your myApp icon on the screen? Exit Xcode and the sim.

Test the App in the Device

1. To test the app in an iOS device, you have to be a paid Developer, then set up the online certificates for the device. Only after the certificates have been installed will Xcode recognize your device and add it to the scheme. Otherwise, the scheme will only show what’s available among the simulators.

You connect the device to the Mac and turn the device on; in Xcode, select the scheme for your device, then click on the Play triangle to build and run it. At lower right you can watch the Xcode console update with your app updates. If you don’t see the console, then go to View > Debug Area > Activate Console.

After I clicked on Play, I got a Build Failed message at the top. I clicked on the triangle icon over the app name in the left column. It said, copyPNGFile Error. Clicking on that error opened the message more fully in the middle pane. I was complaining about not seeing two landscape launch images: /Default-Landscape@2x~ipad.png /Resources/splash/Default-Landscape@2x~ipad.png. I deliberately did not include these. To get rid of this error, do this.

1. In Xcode, click on the File icon over your app’s name in the left column.

2. Open Resources > Splash in that column.

3. You should find names in red. Delete all of those files.

4. Right-click on file and select to Add files to the folder.

5. Select your screens from /platforms/ios/appName/Resources/splash. In Xcode, make sure Copy items if needed and your app icon are both checked. Click on Add.

6. Hold down Alt and click on Product > Clean.

7. Click on the Play symbol and run the app in your device again.

2. There’s a second way to run it in your device. When I plug in my device and type:

cordova run ios

. . . it creates the .dmg file and loads it onto my device. It leaves it up to me to tap the icon on the screen to start it up, unlike Xcode, which loads the app and opens to the app’s home page. I could not figure out how to quit the terminal process, so I used command-w to close the window.

About the /myApp/merges Folder

What if you need to use different versions of pages for different platforms? I needed the home page of my app to be different on Android and iOS. That’s what the /myApp/merges folder is for. The /myApp/merges/ios folder is the same as your /myApp/www folder, so I moved the index.html file to the /merges/ios folder. When I did a cordova platform add android, it created a /merges/android folder. I copied the index.html file there and made the changes for the Android version. So when I do a cordova build ios or cordova build android it will use the correct file for each build.

FastClick.js is not used in some versions of Android. For this reason, I moved the fastClick.js file to /merges/ios, then copiedfastClick.js to /merges/android. I opened fastClick.js in /merges/android and deleted the contents, that way all the links in the html pages would not generate errors due to a missing file reference. It will access the file as normal, but being blank, will not actually do anything.

When styling links for YouTube in the InAppBrowser, onclick=”” works in iOS to open a YouTube link in IAB but not in Android (it didn’t work in my Nexus 7). So I put differnt versions of those pages in /merges/android and /merges/ios, each page with its own link style:


<a href="#" ontouchend="'', '_blank');">link</a>


<a href="">link</a>

If you want to use the same iOS video code in both, then you’ll need to install Chromium’s Crosswalk in the Android app.

For another use of the /merges folder, if you have a /www/css folder and want different style sheets for each app, just create a /css folder inside each /merges platform folder (like /myApp/merges/android/css) and put the css there instead of in a /myApp/www/css folder. That will style each platform differently according to your CSS files.

To quickly test this, simply move the /www/index.html file to its /merges/ios counterpart. Open the index.html file and add the following right after <body>:

 <h2>This index.html page is in the /platforms/merges/ios folder.</h2>

Go ahead and test in your device with cordova build ios. The above text should appear at the top of the screen.

About the /myApp/hooks Folder

If you open /myApp/hooks, you’ll see a readme text file there. That folder is for adding scripts that will execute as part of your CLI operation. For instance, you can add a before_build script which will automatically add all your plugins before the actual build commences. So each time you create a new app, you’ll copy/paste that file into the new app’s /hooks/before_build folder. I’m not familiar enough with this process to explain it here, but if you already know node.js scripting, you might look into it. For instance, this page gives the hooks steps for automatically creating app icons (requires installation of Homebrew and ImageMagick): Other uses would be to add all the usual plugins.

Test Your Code

Ideally, you would have finished all these steps before you began testing your app, but I put them all down here so we could get the Cordova project up and running. I’m putting these steps here for completeness.

1. Double-check that your app meets the HIG (Human Interface Guidelines), the rules Apple uses to determine properly designed apps for the App Store. Link found in the iOS Dev Center online:

2. Double-check that your app does not go afoul of these App Review Guidelines. Link found in the iOS Dev Center online:

3. Make sure your HTML is valid.

4. Validate your Javascript.

5. You may want to minify your JS.

6. Do image optimization/compression.

7. Remove the default folders CLI created in the /www folder: /js, /css, /img if you haven’t already.

8. Make sure all pages which use a Cordova API references this in the <head>:

< script type="text/javascript" charset="utf-8" src="cordova.js"></script>

// Wait for device API libraries to load 
document.addEventListener("deviceready", onDeviceReady, false); 
// device APIs are available

function onDeviceReady() {


Don’t just copy/paste the above everywhere; change src=”cordova.js” to ../cordova.js or even ../../cordova.js, depending on the folder.

9. [Personal note] Don’t forget to add the JavaScript search function to the app:

Update Cordova

1. If you encounter issues with an individual plugin, by all means let your debugging include removing the plugin and adding it again. To do that, follow these steps:

a. In terminal: cordova plugin ls to see the plugins installed. Highlight the plugin you want to remove, and copy it.

b. In terminal: cordova plugin rm and paste in the copied plugin (like this: cordova plugin rm cordova-plugin-inappbrowser). Hit Enter.

c. To install again, in terminal: cordova plugin add and paste in the copied plugin (like this: cordova plugin rm cordova-plugin-inappbrowser). Hit Enter.

Note that Cordova does not have a way to update plugins. If you know of an updated plugin, then you simply following the a, b, c steps above to install the new plugin version.

2. If you need to update Cordova, then do this way:

npm update -g cordova

3. To update a particular platform (perform this command one at a time for each platform):

cordova platform update ios

Add Screenshots for App Store

The App Store requires a screenshot for each size of device your app supports. Images must be at least 72 dpi, in the RGB color space, and the file must be .jpeg, .jpg, .tif, .tiff, or .png. Choose up to 5.

iPhone 3+4 (3.5 Inch)
640 x 960

iPhone 5 (4 Inch)
640 x 1136

iPhone 6 (4.7 Inch)
750 x 1334

iPhone 6 Plus (5.5 Inch)
1242 x 2208

iPad (Air and Mini Retina)
1536 x 2048

Here are a few ways to get screengrabs of your app.

1. Connect the device to your Mac.
2. On the device, go to the screen you want to capture.
3. In Xcode, choose Window > Organizer, and click Devices to display the Devices organizer.
4. In the Devices organizer, select Screenshots under the device.
5. Click New Screenshot for each screen you want.

Or, to capture a screenshot on your device, you press the Lock and Home buttons simultaneously. Your screenshot is saved in the Saved Photos album in the iPhoto app.

If you don’t have a device, then you’ll need to do a screen grab of the pages in a browser and knit them together in an image editor. In the Mac, I use a combination of Chrome with Window Resizer extension, Grab screenshot maker app, and Pixelmater app.

1. I display a page in Chrome and zoom twice to enlarge the text

2. size the width correctly with Window Resizer

3. use Grab to get the “window” and then copy it

4. switch to Pixelmater and create a new file of the correct screengrab dimensions

5. paste the Grab view into Pixelmater

6. delete the unwanted top Chrome browser tab section

7. return to Chrome to scroll up and grab another screen to add to Pixelmater until the screen is filled up.

8. I export as png, saving the filename like screen4.7a-750×1334.png so I know which screengrab goes where in iTunes Connect and what dimensions I made it, incrementing the “a” for separate screenshots. This is tedious work; do as many as you can, though, because this is what sells your work. Choose those screens that show off your app to its fullest!

More about testing

iExplorer App

This app lets you navigate your device’s folder on the desktop. This was good when I wanted to check if the camera shot a picture and what image name it was given. Good also to check the contents of a database. It’s free to use as a demo.


Desktop Safari Web Inspector

Using the Safari browser, you can install your app on your iOS device and monitor its usage on your desktop monitor, including console feedback.


Google Chrome Dev Tools

Open Google Chrome, hit the hamburger options icon > Tools > Developer tools, and click on the mobile device icon. Select various devices from the drop-down menu to see your app in different device configurations.


Other Ways to Test

1. You can run the project in a web server via CLI (although you can’t test all the plugins this way):

cordova prepare ios
cordova serve ios

Open a web browser like Chrome or Firefox and paste the following into the URL field:


Open Firebug or Developer tools, then click on the ios link. Run your code thoroughly to look for problems. When finished, click on the Terminal screen to select it, then on Control + C keys to terminate the server.

I noticed that Developer Tools could not find cordova.js using the cordova serve method. That file is created in the /platforms folder. So you can open platforms/ios/www/index.html in a browser to test.

2. For more testing possibilities, use the weinre (Web Inspector Remote) software at

3. Nice article:

Xcode Settings for Deployment to App Store

These are the settings to change in Xcode to produce the file you’ll upload to the App Store. You do these steps after setting up Development and Distribution provisional files online.

1. Double-click on your .xcodeproj file to open in Xcode.

When double-clicking on xcodeproj name, I got this error: “Project /Users/Steve/Documents/app Name/platforms/ios/app Name.xcodeproj cannot be opened because the project file cannot be parsed.” Xcode did not like the space in the name where I put it in config.xml.
a. I removed space in <name></name> in config.xml.
b. cordova platform rm ios
c. cordova platform add ios
d. cordova prepare ios.
e. Double-clicking on file opened it in Xcode normally.

Click on the filename at far left. The pane at right updates and shows: PROJECT/MyApp and TARGETS/MyApp (that’s how I named it in config.xml <name=). Click on PROJECT/MyApp, then on Build Settings. You should have these headings in blue: Basic, All, Combined, Levels. Below them is a series of bold headings.

2. For the Architectures heading, Base SDK, “Latest iOS” should be selected. This is the latest iOS version this version of Xcode supports.

3. Scroll down to the Code Signing, Debug and Release. To the right, the “iOS Developer” should be chosen for Debug and “iOS Distribution” selected for Release.

4. Now click on TARGETS/MyApp. Exactly the same selections should be made here as well. Under the Code Signing heading is Provisioning Profile. Choose Distribution provisioning profile in the drop-down.

5. Still under TARGETS/MyApp, click on the General link in the menu bar and read the selections to make sure they are correct. Scroll down and look at the listing of icons and make sure none are missing or wrong. Scroll down further and check out the launch images/splash screens and correct any missing or wrong images there.

6. Also, if you don’t have matching provisioning profiles, you’ll be alerted in this space, and a Fix Issue button will give you an opportunity to make amends.

7. Under iPhone, check off all the orientations your app will support. Do the same for the iPad button.

8. Click on “Requires full screen” if your app is not handling multitasking. If you don’t do this, you’ll get a fatal error when uploading your archive to the app store: “iPad Multitasking support requires launch story board in bundle ‘com.companyname.appname’.”

After a Product > Clean, I ended up with two warnings.

For CordovaLib: “Update to recommended settings.” Double-clicking on the warning, I got a box with Build Settings checked and another for: Project ‘CordovaLib’ – Turn on ‘Enable Testability” When Debugging. This will turn on “Enable Testability” for the “Debug” Configuration. Then you click on “Perform Changes.”

For appname.xcodeproj: “Update to recommended settings.” Double-clicking on the warning, I got a box with Build Settings checked and another for: Project ‘appName’ – Turn on ‘Enable Testability” When Debugging. This will turn on “Enable Testability” for the “Debug” Configuration. And another checkbox for: Target ‘appName’ – Adopt “Product Bundle Identifier” build setting. Target ‘appname’ will have its info.plist’s CFBundleIdentifier key set to “$”PRODUCT_BUNDLE_IDENTIFIER)” build setting will be set to “com.companyname.appname”. Then you click on “Perform Changes.”

9. Go ahead and click on the other links in the menu bar to see what’s there.

“Submit for Review”

1. Fill out the Application Assets Template located here:

2. You’ll need to go online to the Apple Developer site at (preferably using the Safari browser), sign in, and click on the iTunes Connect link. Click on Manage Your Applications and either Add New App, or choose an existing app to upgrade. Follow the steps online and transfer all the information into the fields from the Application Assets Template you just filled out, as well as the screengrabs you made.

Steps I took Jan. 2016 to upload a revised app:

  1. Opened Safari web browser (necessary for best experience with Apple).
  2. Clicked on Member Center and signed in.
  3. iTunes Connect, sign in again.
  4. My Apps icon.
  5. Select the app icon to update.
  6. Clicked on + VERSION OR PLATFORM and chose iOS. Then enter the store version number you have in config.xml (“8.0”). Click Create.
  7. Click on the screenshots tabs to make sure all are filled.
  8. Add info in What’s New box.
  9. Update any other information you see on the page. In Notes? you can write anything that will help the reviewer with checking your app.
  10. At the bottom, check whether you want to release the app manually or as soon as it has been approved.
  11. Click on Save at top. Leave this page open and go back to Xcode.
  12. Unhook your device from the computer (if it was connected). Follow the next steps.

Upload a Binary to the App Store

1. A binary of the app is the compiled version of the app that is made up of 0’s and 1’s. To compile your app for the App Store, first make sure your device is unconnected.
2. If you made any last-minute changes to the PhoneGap project, do a cordova prepare ios command in a terminal window.
3. In Xcode, do a Product > Clean while holding down the option key.
4. Then set Product > Destination > Generic iOS Device.
5. Then do a Product > Archive and wait for the app to build.
6. The Organizer window should open (if it doesn’t: Window > Organizer).
7. Click on your app name in Organizer, make sure of the version, then click on Upload to App Store…
8. Select a Dev Team for provisioning (I choose my name). Click Choose.
9. Next screen will list and Provisioning Profile. Check the PP and read below.

At this point, sometimes my PP is XC: and that’s not right. In that case, hit Cancel, right-click on the app name, and choose Delete Archive. Minimize Organizer, then in Xcode click on appName under PROJECT and under Code Signing you’ll need to select the correct Code Signing ID for Release, both rows. (It should not be iOS Developer.) Now go back to step 3 and try again.

Assuming your PP is correct, hit Submit. Do something else while the Archive is being uploaded.

If you get more errors, check out the Troubleshooting section of the App Distribution Guide by Apple:

When finished, you’ll get a Submission Successful screen. Hit Done.

7. Now switch to your app’s page, scroll way down, and click on Build +. You’ll need to wait a while before it appears if your app is still processing. Select your app, then Done. You’ll get a “Processing” note at times in this box; just come back later and refresh the screen.

8. If you successfully hit Done, then scroll up and hit Save, then Submit for Review.

9. Answer the questions on the page and hit Submit. The status at upper left should now say Waiting For Review. You may now log off of the Apple site. At this point it’s a waiting game as Apple techs review your app. Apple will actually send you emails and notifications in your device on the changing status of your app. While waiting, you can perform the next few steps.

Back up your files

1. Open Keychain Access (click on the magnifier icon at top right of your desktop and type in “keychain” and select the app). Right-click on the certificates and export each one to your computer (giving each one a name similar to the name in the Keychain Access line), then send it off to a safe backup location. Warning: if these files are lost, you won’t be able to upload successive versions of your apps to the App Store.

2. Back up your password files. Go to /Users/[name]/Library/Keychains and copy the .keychain files there to a safe place. /Library is a hidden folder.

To show the hidden files, type in Terminal:

defaults write AppleShowAllFiles TRUE

. . . and hit Return. Then type in Terminal:

killall Finder

. . . and hit Return. The desktop will go blank, then after a while will refresh. Open the Documents folder, then in Finder, Go > Enclosing Folder, and see the hidden files in gray, including /Library.

To hide the hidden files, repeat both commands, but substitute FALSE in place of TRUE.

3. Now would be a good time to create a “snapshot” in Xcode of your work at this point in time (in Xcode, File > Create Snapshot). A Snapshot is a copy of the project stored away. You’ll be able to revert to this version at a later date if you need to. If everything is working fine, then do a File > Create Snapshot of your current working project.

You can delete these snapshots by going to Window > Organizer, click on Projects at top, then on the project name at left. After clicking on a Snapshot, click on the Delete Snapshot icon at lower right. This will free up a lot of memory after you’re sure you will no longer need the earlier versions. If you need to revert to an earlier version (snapshot) of the project, you will first create a new folder in Finder, then click on the Restore Snapshot icon to save it to that folder. You’ll have two versions of the project; this way the reverted version will not overwrite the previous version.

Further Recommended Steps

If you are going to be involved with PhoneGap regularly, keep up to date with the release announcements of upcoming versions, updated plugins, and other news.

Familiarize yourself with the Cordova site:

Read the PhoneGap Blog:

Subscribe to the PhoneGap Twitter feed:

Be friends on Facebook:

Join Google Groups:!forum/phonegap

Mac®, OS X®, Apple®, Xcode®, App Store℠, iPad®, iPhone®, iPod® and Finder® are trademarks of Apple Inc.

5 thoughts on “Using Cordova CLI on Mac OS X to build iOS apps – updated 5/2016

  1. Pingback: Using PhoneGap 3.0 CLI on Mac OS X to Build iOS and Android Projects | iPhone Dev Log

  2. “The pane at right updates and shows: PROJECT/MyApp and TARGETS/MyApp (that’s how I named it in config.xml <name=)". — Im a bit confused what exactly is "it"? What would PROJECT/MyApp and TARGETS/MyApp be named if you didn't change there names? (Im new to cordova)

  3. I am trying to use cordova cli on a mac os x el capitan 10.11. I’ve installed npm, cordova cli, ios deploy, ios sim and have xcode. But when I enter the command “cordova requirements” it shows that :

    Requirements check results for ios:
    Apple OS X: installed darwin
    Xcode: not installed
    xcode-select: error: tool ‘xcodebuild’ requires Xcode, but active developer
    directory ‘/Library/Developer/CommandLineTools’ is a command line tools instance ios-deploy: not installed

    ios-deploy was not found. Please download, build and install version 1.8.3 or greater from into your path, or do ‘npm install -g ios-deploy’
    Error: Some of requirements check failed
    I have all of the above installed on my mac, still getting these errors, please?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s