caniuse-lite packs the caniuse-db dataset down for browser bundles

Why the full database is the wrong shape for a browser

The full data behind Can I use is described in the README as incredibly useful for any front end developer, and the website displays all of it. The problem appears when the same data has to travel inside a page. In automated tools many of those fields go unused, and while that does not matter for server side consumption, on the client the less JavaScript you send to the end user the better.

That is the entire premise of caniuse-lite. It is a smaller version of caniuse-db with only the essentials, aimed at contexts where size on disk is important, for example usage in web browsers. The README calls it an almost drop-in replacement for caniuse-db, with API differences that are small and detailed.

The users are therefore narrow and specific. You are a bundler plugin, a build-time transform, or a browser-side script that needs to know whether a feature is supported by a browser, and you care about the bytes that data adds to your bundle. You are not a person who wants to browse support tables.

If your use is server side, or if you need fields that the lighter dataset drops, this is the wrong package and the savings do not apply. The rest of this article looks at what survives the trimming, how the packing works, and what changes when you unpack it.

Three ways the packed format shrinks the data

The README lists the compression techniques, and they are the interesting part of the design.

The first is that null array entries are converted into empty strings. In the source data, absent values are represented as null, which costs characters in a JSON payload. Replacing them with empty strings removes that overhead while keeping the array shape and the index positions intact.

The second is that support data is represented as an integer rather than a string. Support information that would otherwise appear as a readable string in the source becomes a number, which is shorter once encoded.

The third is that base62 references are used instead of longer human-readable keys. The identifiers that name browsers, features or regions are stored as base62 values, so a repeated key costs a fraction of the characters it took before.

None of this is clever compression in the gzip sense. It is a change of representation that keeps the same information in a smaller textual form, which matters because these files are parsed by JavaScript at build time or at runtime rather than streamed to a network.

The result is a packed dataset in the data directory of the package, alongside a dist directory that holds the code which puts it back together.

The unpacker API reassembles a caniuse-db shaped result

The packed data is reassembled through functions exposed by the module, into a larger format that is mostly compatible with caniuse-db. The entry point is a namespace import:

import * as lite from 'caniuse-lite'

The agents export is the replacement for the full data.json file. Instead of that large file, caniuse-lite provides a data subset carrying the browser, prefix, prefix_exceptions, usage_global and versions keys from the original, plus one addition: a release_date key holding release dates as timestamps for each version.

{
  "release_date": {
    "6": 998870400,
    "7": 1161129600,
    "8": 1237420800,
    "9": 1300060800,
    "10": 1346716800,
    "11": 1381968000,
    "5.5": 962323200
  }
}

The feature method takes a file from data/features and converts it into something that more closely represents the caniuse-db format, and only the title, stats, status and shown keys are kept from the original data. The features index exists as a way to query all of the features listed in the caniuse-db dataset, and the documentation is clear that you need to run values from that index through the feature method to get a human-readable format.

The region method takes a file from data/regions and converts it into a caniuse-db-like shape, but only the usage data is exposed here, which is the data key in the original files.

The packer script that rebuilds the dataset

The repository shows how the packed data is produced, which matters if you want to regenerate it against a newer source dataset.

The package.json scripts describe a pack target that copies the MDN data and rebuilds the packed output:

    "pack": "node copy-mdn.js && rm -Rf data && node src/packer/index.js",

Two other scripts in the same file check the result. The integration test runs the consumer script and discards its output:

    "test:integration": "node ./consumer.js > /dev/null",

and the unit tests are run with uvu against the test files, while the lint script runs oxlint. The umbrella test script runs the pack step first and then every test script in turn, which means a full test run rebuilds the dataset before it checks it.

The source of the copied data is visible in the dev dependencies, where @mdn/browser-compat-data is pinned to 8.1.6 and caniuse-db is pinned to 1.0.30001817, the same version as this package itself. The repository root also carries copy-mdn.js, check-mdn-bcd.js, check.js, commit.js and consumer.js, which together cover the copy step, the consistency checks and the consumer side of the integration test.

The project uses pnpm, with a pnpm-lock.yaml and a pnpm-workspace.yaml at the root, and a .devcontainer.json for a reproducible development container.

What you lose when the unused fields are dropped

The trimming is where the real trade-off lives, and the documentation is precise about it.

Three things are lost. The agents export no longer offers the full data.json content, only the browser, prefix, prefix_exceptions, usage_global and versions keys, so anything else you expected to read from the original file is simply not there. The feature method keeps only title, stats, status and shown, so per feature metadata such as descriptions, notes or links is absent. The region method exposes only the usage data, the data key from the original region files, so region metadata beyond usage numbers is not available.

There is a second, subtler consequence. The features index is a way to query the feature names, but the documentation states you will need to use the feature method on values from that index to get a human-readable format. The index is therefore not the same shape as the data it points at, and code that treats the index as final output will look wrong.

A third is the version coupling. The package version, 1.0.30001817, is tied to the caniuse-db version 1.0.30001817 in the dev dependencies, and the data reflects whatever caniuse-db snapshot that is. There are no GitHub releases for this repository, so the version number in package.json is the only artifact reference you get, and it is the one to pin if you need reproducible builds.

CC BY 4.0 and the attribution you owe the data

The licence situation is unusual for a package that ends up inside a JavaScript bundle, and it is worth reading rather than skimming.

The data in this repository is made available under a CC BY 4.0 licence, and the README asks that for attribution you mention somewhere that the source is caniuse.com. If you have questions about using the data for your project, the README points to a contact page for the maintainer.

CC BY 4.0 is a data licence rather than a software licence. It is compatible with commercial use and with bundling, and it does not require you to publish anything about your own code. What it does require is attribution, and the practical question for a team is where that attribution lives in a shipped application, since a comment in a bundled file may not be visible to anyone who did not build it.

This is different from the obligations that come with using a piece of software under MIT, where the requirement to keep notices travels with copies of the source. Here the obligation attaches to the data, and the README's instruction is simply to credit caniuse.com.

For a reporting channel, the README points at the Tidelift security contact, with Tidelift coordinating the fix and disclosure, and the package.json lists both Tidelift and Open Collective as funding routes for the browserslist organisation.

caniuse-db itself, or the MDN dataset, as the alternative

The alternative that matters is caniuse-db, the full dataset this one is derived from. It is present in the repository as a dev dependency at the same version number, and the packer is what turns it into the smaller form. The difference in approach is exactly the trade the README describes. caniuse-db keeps every field of the original data in a human-readable form, so it can answer any question about support data, and it does not need a runtime unpacking step. caniuse-lite keeps the essentials in a packed form and reconstructs them on demand, which is smaller to ship and slightly more work to use.

The choice follows from where the code runs. A build script on a server that queries a dozen features has no size problem and no reason to pay for an unpacking layer, so caniuse-db is the sensible dependency there. A browser bundle that has to answer a support question at runtime has the opposite profile, and that is the case caniuse-lite was built for.

A third option exists in the repository's own tooling. The @mdn/browser-compat-data package is a dev dependency, the copy-mdn.js script copies from it, and check-mdn-bcd.js checks the two sources against each other. So the MDN compatibility data is present in the pipeline as a second source of browser support information, and the consistency check between the two datasets is part of how this package is built rather than something a consumer sees at runtime.

Editorial conclusion

caniuse-lite earns its place in any browser bundle that has to answer a browser support question at runtime, since it keeps the agents, feature and region data that tools read and drops the rest. It is the wrong dependency for a build script that needs every field of caniuse-db, for a Node tool with no size constraint, or for a project that cannot carry a Creative Commons attribution requirement. Verify first which fields your own code touches, since lite.feature keeps only title, stats, status and shown, lite.region exposes usage data alone, and lite.agents is a subset of the original keys plus release_date, then check the installed version number against the caniuse-db version your project expects.

Frequently asked questions

Official sources

1. browserslist/caniuse-lite on GitHub
2. Issues
3. License: CC-BY-4.0
4. README