Edit: As I find more things, I'll post them to the bottom of this blog post.

For folks who have seen me present on PhoneGap/Cordova, you know I'm a huge fan of Ripple. Ripple was (is, see details) a Chrome extension that allows you to run PhoneGap/Cordova applications in the browser. Ripple included a UI that gave you a pseudo-mobile view of your application and a way to emulate various features including the camera and the accelerometer. While not as good as a real device, it was incredibly useful for development.

Unfortunately, sometime around the PhoneGap 2.6 timeframe, something went wrong. Whether it be a Chrome issue or something different in PhoneGap, Ripple stopped working properly. For the last few months, a new developer, Gord Tanner, has been working on an update to the Ripple project at Apache. Previously, Ripple was a Chrome extension and was managed by some folks from Blackberry. Now you can find Ripple at Apache:http://ripple.incubator.apache.org/.

In this blog post, I'm going to describe how to use Ripple. Please read this carefully. Ripple has changed. It is still very cool, but how you interact with it and PhoneGap has been changed.

First and foremost - you must remove the Ripple Chrome extension if you have it installed. Leaving it installed will conflict with the new Ripple. If you don't know how to do that, simply go to your Chrome Extensions page, find Ripple, and disable or remove it. If you still see the little blue Ripple icon to the right of the URL bar than you haven't done it right.

Next - go to the command line. If you don't have npm, then please install it by installing Node. If you have done anything with PhoneGap or Cordova in 3.0 then you already have this. If not, now is the time to fix it. If you have npm installed, then install ripple-emulator:

npm install -g ripple-emulator

Next, create a new Cordova project. (This should work in PhoneGap too.)

cordova create foo

CD into your new project, add Android as a platform, and prepare it so the files are laid out.

cordova platform add android
(lots of stuff output here...)
cordova prepare

Ok, this is where Ripple acts differently. I mentioned earlier that you needed to remove the old extension. So how do you use Ripple? From the root of your project, you can run the ripple command. You need to tell Ripple where your Android code exists. You can do this by running it from (yourproject)/platforms/android/assets/www or by passing a path argument:

ripple emulate --path platforms/android/assets/www

And just to mix things up a bit - a screenshot from OS X to go with the Windows shots above:

Edit as of 12:14AM - thanks to Jonathan Rowny: You do not need to specify a path. If you do "ripple emulate" in the root, it just plain works.

At this point, Ripple actually fires up Chrome for you and opens it to your application:

And that's it! There's a bit more detail at the project home page. Check it out and let me know if you run into any issues. I've successfully run it now on Windows and OS X.

Additional Notes on Nov 5 (yes, about 30 minutes after I posted): Yes, if you want to use plugins (i.e. any core feature), you still have to install them the normal way even if you are using Ripple. Don't forget that. Secondly - every time you edit your code, you're going to need to re-prepare your project. What I recommend is - use a tab to fire up Ripple and another tab to simply run the prepare. You can even use a Grunt watcher to handle this for you.

Additional Notes on Jan 2, 2014: If you ever launch Ripple and see this in the display: Error: static() root path required (lots more crap beneath) it may be that you only added iOS support to your project and Ripple defaults to an Android device. Just switch to an iOS device and it should remove the error. Obviously if you add Android as a platform as well it will go away.

Additional Notes on Jan 11, 2014: A caveat to the first note. When you edit your code, you do not need to run cordova prepare. Ripple does it for you. But you do need to rerun "ripple emulate" to refire the simulator. If you just reload the browser tab it won't show the latest changes. So you have a choice. You can either keep running "ripple emulate", or do "cordova prepare" in another Terminal tab so you can reload the same tab. (Or use the Grunt task idea.)