Zepto.js: a jQuery-compatible library for modern browsers

The problem Zepto.js solves, and for whom

Zepto.js targets a narrow gap. You want jQuery's calling style, but you are shipping to phones and you do not want to pay for jQuery's full surface. The README states the project is a minimalist JavaScript library for modern browsers with a largely jQuery-compatible API, and that if you use jQuery, you already know how to use Zepto. That compatibility is the selling point, not the feature list.

The audience is a front-end developer on a small page or a single-page mobile view who is already fluent in $(selector), on(), and $.ajax. The library is not for you if your codebase leans on jQuery plugins that expect the full jQuery object, or if you are supporting old desktop browsers. The README describes the ie module as support for Internet Explorer 10+ on the desktop and Windows Phone 8, and there is a separate ios3 module that only polyfills String.prototype.trim and Array.prototype.reduce. Neither of those is a general legacy-browser story.

Modules in src/ and how a build becomes dist/zepto.js

Zepto is assembled, not consumed whole. The README says modules are individual files in the src/ directory, and the distribution is produced by a build. The default set is zepto, event, ajax, form, and ie. Everything else is opt-in: detect, fx, fx_methods, assets, data, deferred, callbacks, selector, touch, gesture, stack, and ios3.

The dependency graph matters more than the list. The README states the deferred module provides $.Deferred and depends on the callbacks module, so selecting deferred without callbacks is not a valid build. The selector module is described as experimental support for jQuery CSS extensions such as $('div:first') and el.is(':visible'), which is the piece people miss when they assume Zepto is a drop-in replacement. The touch module fires tap- and swipe-related events and works with both touch events on iOS and Android and pointer events on Windows Phone. The gesture module adds pinch events on top of that. The assets module is marked experimental and is about cleaning up iOS memory after removing image elements from the DOM.

This is the design trade-off in one place: you get a small file only if you are willing to name exactly which behaviours you need. The default bundle is a starting point, not a recommendation.

Installing Zepto.js and running a custom build

The README points to zeptojs.com for an extended introduction, downloads, and documentation, and the official site offers a download of the default distribution. That is the fastest path if the default module set is enough. If it is not, you build from source, and the README says you will need Node.js installed.

From a checkout of the repository, install the build dependencies and produce the default distribution:

npm install
npm run-script dist

The README states the resulting files are dist/zepto.js and dist/zepto.min.js. To trim or extend the bundle, set the MODULES environment variable to the space-separated module names you want and run the same script:

MODULES="zepto event data" npm run-script dist

On Windows the README gives a two-step form instead, setting the variable first and then running the script:

SET MODULES=zepto event data
npm run-script dist

If you prefer the CoffeeScript entry point, the README notes that installing CoffeeScript globally lets you run make directly, with coffee make dist, and the same MODULES override applies. The README does not document a rollback procedure if a custom build drops a method your page depends on, so keep the previous dist/zepto.js until you have checked the page.

Where Zepto.js breaks: selectors, release cadence, and old browsers

The most common failure mode is selector behaviour. jQuery CSS extensions such as :first and :visible live in the optional selector module, and the README calls that module experimental. A page that works against jQuery can therefore fail after a Zepto build that omits selector, and the failure shows up at runtime in the browser rather than at build time.

The second limitation is release cadence. The most recent release listed is v1.2.0 from 2016-07-13, followed by v1.1.7 on the same day and v1.1.6 in 2014. The repository is not archived, and the last push was on 2026-05-07, so there is activity on the default branch, but the tagged releases are old. If your dependency policy requires regular versioned releases, Zepto.js does not satisfy it. Note also that the README's bug-reporting instructions tell you to check whether a bug is already fixed on the master branch since the last release, which acknowledges that fixes can sit unreleased.

The third limitation is browser coverage. The ie module covers Internet Explorer 10+ on the desktop and Windows Phone 8. There is no IE9 path, and the ios3 module exists only to supply String.prototype.trim and Array.prototype.reduce where they are missing. Zepto.js is the wrong tool for a site that must support older desktop browsers.

Finally, the build toolchain is old. The package.json devDependencies pin uglify-js 2.4.x, express 3.1.x, coffee-script 1.5.x, and shelljs 0.1.x. Expect to spend time on the build environment itself if you build on a current Node.js installation.

Zepto.js against jQuery and against writing plain DOM code

The obvious alternative is jQuery itself. The difference is scope rather than syntax. jQuery ships its own selector engine and the full set of CSS extensions by default, so $('div:first') and el.is(':visible') work without an opt-in module. Zepto.js makes those behaviours optional and experimental, which is exactly how it stays small. If your code depends on jQuery plugins or on selector extensions you have not audited, jQuery is the safer choice; if you use a narrow slice of the API and control every call site, Zepto lets you pay only for that slice.

The other alternative is dropping a library altogether and using querySelectorAll, addEventListener, and fetch directly. That removes the build step and the dependency entirely, at the cost of the chaining style and the cross-browser shims you would otherwise get from the event, ajax, and form modules. For a page with a handful of interactions, plain DOM code is smaller than any build of Zepto. For a page with many call sites, the jQuery-compatible API is the reason to keep it.

Licence, maintenance, and what a Zepto.js upgrade costs

The README states Zepto.js is licensed under the terms of the MIT License, and the repository carries an MIT-LICENSE file at the top level while package.json lists "license": "MIT". Treat the MIT terms as the operative ones and read the licence text yourself; this is a description of the repository, not legal advice.

Upgrade cost is unusual here because there is little to upgrade to. The newest release is v1.2.0 from 2016-07-13, so most teams will be pinned to that tag or to a commit on main. The repository is not archived, and the last push was on 2026-05-07, which means the default branch can move ahead of the last release. If you build from main, you are consuming unreleased code, and the README's own bug instructions assume that distinction.

Running the test suite is the practical check before adopting a build. The README says tests need PhantomJS, installed with brew install phantomjs on OS X, and that npm test runs the automated tests. It also describes npm start, which runs a test server you can open from browsers and devices at http://your-ip-address:3000/, with failures reported to the console you started the server in. That device-facing server is the part worth using, because selector and touch behaviour differ by browser.

What to check before you ship a Zepto.js bundle

Start from the module list, not the API docs. Write down every Zepto method your page calls, then map each one to the module that provides it in the README's table. Anything that depends on jQuery CSS extensions needs selector, and selector is experimental. Anything using $.Deferred needs callbacks as well, per the README. Anything using animate or fade needs fx or fx_methods.

Then build with an explicit MODULES value rather than the default and load the page in the browsers you actually support, including a touch device. The README's test server, started with npm start and reached at port 3000, is designed for exactly that. If a method is missing after the build, the error will be a TypeError in the browser, not a build failure, so the manual pass is not optional.

Finally, decide whether you are pinning to v1.2.0 or tracking main. Pinning gives you a fixed artefact that matches the last release. Tracking main gives you whatever has been pushed, most recently on 2026-05-07, with no release notes to read. Pick one deliberately.

Editorial conclusion

Adopt Zepto.js for a small, modern-browser page where you will build a custom bundle with MODULES and accept that the last tagged release is v1.2.0 from 2016-07-13. Do not adopt it if you need jQuery's full selector engine, an actively released dependency, or IE9 support, since the ie module only covers Internet Explorer 10 and Windows Phone 8. Before committing, verify the module set you need actually exists in src/, run npm run-script dist with your MODULES list, and check that the resulting dist/zepto.js behaves in your target browsers.

Frequently asked questions

Official sources

1. Issues
2. madrobby/zepto on GitHub
3. Project website
4. README
5. Releases