The Node.js Command-line Interface for PhoneGap

PhoneGap ships with a simple set of scripts that you can use to create a new project from the command-line. Newly created projects include scripts to build, emulate, and deploy your app.

There is another command-line interface for PhoneGap written in JavaScript for node.js that the PhoneGap/Cordova documentation does not mention. I don’t know why this is. Maybe it will be documented in future releases. Hopefully I am not stealing the PhoneGap team’s thunder by writing about it!

What I really like about this package is that it bundles the PhoneGap/Cordova release. So by installing the package, you have effectively installed PhoneGap. It also provides some fantastic guidance about how to structure a multi-platform PhoneGap application.

The documentation recommends installing the CLI globally by running:

> npm install -g cordova

However, if you install the CLI locally you will be able to have different PhoneGap versions for different projects. So here are the steps I follow when starting a new PhoneGap project.

Install node.js, and add ./node_modules/.bin to your PATH environment variable.

Create a directory for your new project:

> mkdir myproject && cd myproject

Create a package.json for your project:

> npm init
# Follow the (many) prompts... or just hit enter a bunch of times.

Install the PhoneGap CLI:

> npm install cordova --save

Now that the CLI is installed, let’s see what it can do for us:

> cordova

    cordova command [options]

Global Commands

    create [path] [id] [name] ........... creates a cordova project in the specified
                                          directory optional name and id (package
                                          name, reverse-domain style)

Project-Level Commands

    platform(s) [add|remove|ls [name]] .. adds or removes a platform, or lists all
                                          currently-added platforms
    plugin(s) [add|remove|ls [path]] .... adds or removes a plugin (from the specified
    	                                  path), or lists all currently-added plugins
    prepare [platform..] ................ copies files into the specified platforms, or
                                          all platforms it is then ready for building
                                          by Eclipse/Xcode/etc
    compile [platform..] ................ builds the app for the specified (or all)
    build [platform..]................... alias for prepare and then compile
    emulate [platform..] ................ starts emulator for the specified (or all)
                                          platforms, then deploys application to
    run [platform..] .................... deployes the application to the specified
                                          (or all) platform devices, which must be
                                          connected and configured for running via
                                          your machine
    serve <platform> [port] ............. runs a local web server for the www/
                                          directory of the given platform the default
                                          port is 8000
                                          note that you must edit the native code to
                                          point at the server!
    ripple <platform> [port] ............ uses the serve command as a base and then
                                          wraps the server with ripple to test your
                                          app in your desktop browser
    help ................................ shows this!

Command-line Flags/Options

    -v, --version ....................... prints out this utility's version
    -d, --verbose ....................... debug, or verbose, mode Makes this utility
                                          very chatty, logging everything it does,
                                          including redirecting output of commands
                                          it shells out to back to stdout

Example usage

    $ cordova create Baz
    $ cd Baz
    $ cordova platform add android
    $ cordova build
    $ cordova serve android

The help output shows global commands and project-level commands. The only global command is create. Let’s create a new project in the directory we created above:

> cordova create . com.myproject MyProject

This gives us a project tree like this:

> tree -I node_modules --charset ascii
|-- merges
|-- package.json
|-- platforms
|-- plugins
`-- www
    |-- config.xml
    |-- css
    |   `-- index.css
    |-- img
    |   `-- cordova.png
    |-- index.html
    |-- js
    |   `-- index.js
    |-- res
    |   |-- icon
    |   |   |-- cordova_128.png
    |   |   |-- cordova_16.png
    |   |   |-- cordova_24.png
    |   |   |-- cordova_256.png
    |   |   |-- cordova_32.png
    |   |   |-- cordova_48.png
    |   |   |-- cordova_512.png
    |   |   |-- cordova_64.png
    |   |   |-- cordova_android_36.png
    |   |   |-- cordova_android_48.png
    |   |   |-- cordova_android_72.png
    |   |   |-- cordova_android_96.png
    |   |   |-- cordova_bb_80.png
    |   |   |-- cordova_ios_114.png
    |   |   |-- cordova_ios_144.png
    |   |   |-- cordova_ios_57.png
    |   |   `-- cordova_ios_72.png
    |   `-- screen
    |       |-- android_hdpi_landscape.png
    |       |-- android_hdpi_portrait.png
    |       |-- android_ldpi_landscape.png
    |       |-- android_ldpi_portrait.png
    |       |-- android_mdpi_landscape.png
    |       |-- android_mdpi_portrait.png
    |       |-- android_xhdpi_landscape.png
    |       |-- android_xhdpi_portrait.png
    |       |-- blackberry_transparent_300.png
    |       |-- blackberry_transparent_400.png
    |       |-- ipad_landscape.png
    |       |-- ipad_portrait.png
    |       |-- ipad_retina_landscape.png
    |       |-- ipad_retina_portrait.png
    |       |-- iphone_landscape.png
    |       |-- iphone_portrait.png
    |       |-- iphone_retina_landscape.png
    |       |-- iphone_retina_portrait.png
    |       `-- windows_phone_portrait.jpg
    |-- spec
    |   |-- helper.js
    |   |-- index.js
    |   `-- lib
    |       `-- jasmine-1.2.0
    |           |-- MIT.LICENSE
    |           |-- jasmine-html.js
    |           |-- jasmine.css
    |           `-- jasmine.js
    `-- spec.html

13 directories, 49 files

In the www folder we get the standard PhoneGap project template, with assets for every major mobile platform. The plugins folder, naturally, is for plugins. The platforms folder is where the project files for each platform will live. The merges folder is where you keep platform-specific code that will be substituted into each platform’s build step.

Let’s wrap up by getting our project running in the iOS simulator. First, add the platform:

> cordova platform add ios

Now, build it:

> cordova build ios

Build is an alias for prepare and compile. Prepare will copy the source files into the platform-specific directory and apply any applicable merges. Compile builds the platform-specific package. Now launch the iOS simulator:

> cordova emulate ios

That’s it, we’re up and running!

There’s a lot more to this tool, and I’m something of a nerd when it comes to slick command-line interfaces, so I hope you’ll stick with me as I return to it from time to time.

comments powered by Disqus