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
Synopsis
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)
platforms
build [platform..]................... alias for prepare and then compile
emulate [platform..] ................ starts emulator for the specified (or all)
platforms, then deploys application to
emulator
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.