Moving from Zepto to jQuery

I recently had the opportunity to port a large, moving mobile web codebase from Zepto to jQuery. Thanks to Zepto's fairly complete API compatabilty this was fairly straight forward. For the most part, Zepto is a subset of jQuery, so you're going to an environment of less functionality to more functionality. That said, there are a few differences. Here are some things worth looking for:

  1. JSONP: Older versions of Zepto had you constructing your own callback url. On the brightside, it used a completely different method, so it's easy to grep for. If you're dealing with a Zepto before 1.0, or even devs who are used to working with Zepto pre 1.0, ack for "ajaxJSONP" (the method is deprecated, but remains). jQuery doesn't have a ajaxJSONP method, so this is definitely something that could break.
  2. data: The basic implementation of data in Zepto only stores strings. In jQuery, you can store complex objects. This is a place where jQuery is giving you more functionality, so if you're going from Zepto to jQuery you should be ok. If you're going in the opposite direction, you're going to have to do some ack'ing.
  3. Promises / Deferreds: Zepto doesn't return promise objects from its ajax calls. If you've added installed the popular Simply Deferred library into your Zepto install, you'll be just fine when you swap Zepto out for jQuery. I haven't tried this in the opposite direction. My hunch is that you'd be fine, but definitely watch for it.
  4. Touch events: jQuery lacks the touch events that Zepto provides. We grabbed just the touch portion out of jQuery mobile and threw it on top of jQuery and the compatibility has been very good. We've found a few strange interaction, but they were usually with some overwrought code. If you're just using tap and swipe, you're probably going to be ok. jQuery Mobile touch code also provides a ghost click interceptor and is a little bit better about making it easy to override some of the threshold values they use. Zepto has made some choices that cause issues and don't seem to be getting fixed.
  5. selector differences: One of the most subtle issues was finding that there were subtle issues with selectors, for instance, in jQuery if I have the code:
//<div class="myclass">
//    <div class="mysubclass">
//    </div>

var j  = jQuery('.myclass').find('.myclass .mysubclass');
// j has length 0 -- no elems found;

var z = Zepto(class').find('.myclass .mysubclass');
// z has length 1 -- found the element

You might be scratching your head and asking why on earth you would write that, but I did find a real world example of this biting us. The engineer didn't want to add another class to the element they were looking for, but also didn't want to use the very general class name as a selector with no namespacing. So they added the current element to the find statement, saw that it worked in Zepto and went on with their lives. While doing some manual testing I realized that this caused an issue under jQuery.

I can't say this is a conclusive list, and you should definitely spend some time in the Zepto's github issues section, but this is a good place to start your sweep.

One last thing. You're going to shake your head, but if you're just doing an experiment, and you're aware of all the above issues and you're moving from the smaller, more constrained Zepto to jQuery, you can literally do this and expect pretty much everything to work:

window.Zepto = window.jQuery

That's a testament to...I don't know what. Zepto? jQuery? Javascript? Sound engineering? Sensible APIs? Take your pick.