{"id":13499900,"url":"https://github.com/kiwix/kiwix-js","last_synced_at":"2025-10-18T14:20:28.617Z","repository":{"id":5853937,"uuid":"7070674","full_name":"kiwix/kiwix-js","owner":"kiwix","description":"Fully portable \u0026 lightweight ZIM reader in Javascript","archived":false,"fork":false,"pushed_at":"2024-05-01T09:11:31.000Z","size":42029,"stargazers_count":269,"open_issues_count":89,"forks_count":128,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-05-01T11:34:29.013Z","etag":null,"topics":["chrome-extension","edge-extension","firefox-extension","kiwix","offline","pwa","ted","webextension","wikipedia","zim"],"latest_commit_sha":null,"homepage":"https://www.kiwix.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiwix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-GPLv3.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kiwix","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2012-12-08T18:34:41.000Z","updated_at":"2024-05-04T17:27:27.155Z","dependencies_parsed_at":"2023-09-23T04:10:35.786Z","dependency_job_id":"79915995-cca0-4c47-8c79-6d97e3a1615a","html_url":"https://github.com/kiwix/kiwix-js","commit_stats":{"total_commits":764,"total_committers":37,"mean_commits":20.64864864864865,"dds":0.6701570680628273,"last_synced_commit":"b9db118e75387db9dfc69fbf656f1098a0f65ed2"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiwix","download_url":"https://codeload.github.com/kiwix/kiwix-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chrome-extension","edge-extension","firefox-extension","kiwix","offline","pwa","ted","webextension","wikipedia","zim"],"created_at":"2024-07-31T22:00:46.476Z","updated_at":"2025-10-18T14:20:23.585Z","avatar_url":"https://github.com/kiwix.png","language":"JavaScript","funding_links":["https://github.com/sponsors/kiwix"],"categories":["JavaScript"],"sub_categories":[],"readme":"![Kiwix JS 4 0 Anniversary](https://github.com/kiwix/kiwix-js/assets/4304337/97c639ef-a943-45b8-baf9-80aba2bc6ac7)\n\n# Kiwix JS\n\nKiwix is your gateway for offline access to vast web resources like Wikipedia, Stackexchange, Project Gutenberg, TED Talks, and much more. These resources are\npackaged as highly compressed ZIM archives available for free from Kiwix. Learn more about the open-source Kiwix project on our main [website](https://www.kiwix.org/).\n\nKiwix JS is our official HTML5/JavaScript version, primarily designed for browser extensions. Grab our free extension from the Mozilla, Chrome, and Edge extension\nstores. Check out the [Store links](#officially-supported-platforms) for more details. We also offer an offline-first Progressive Web App (PWA) version at\nhttps://browser-extension.kiwix.org/current/. For a fully featured PWA based on Kiwix JS, visit https://pwa.kiwix.org.\n\nTo get started with Kiwix JS, download a free content archive ([Usage](#usage)), select it on your device, and start exploring articles. You can access the entire\ncontent of Wikipedia in your language, including images and audiovisual content, offline. Ideal for users with expensive, intermittent, slow, unreliable, or censored\ninternet access. You can even load ZIM archives shared on a USB stick or external hard drive. No internet? No problem!\n\nKiwix supports all content in the [OpenZIM format](https://wiki.openzim.org/wiki/OpenZIM), including full support for [Zimit content](https://youzim.it/) (based on\nthe Web Archive format), both Zimit Classic and Zimit v2.0. Note: Some content requires your browser to support Service Workers.\n\n[![Build Status: Continuous Integration](https://github.com/kiwix/kiwix-js/workflows/CI/badge.svg?query=branch%3Amain)](https://github.com/kiwix/kiwix-js/actions?query=branch%3Amain)\n[![Build Status: Release](https://github.com/kiwix/kiwix-js/workflows/Release/badge.svg?query=branch%3Amain)](https://github.com/kiwix/kiwix-js/actions?query=branch%3Amain)\n[![CodeFactor](https://www.codefactor.io/repository/github/kiwix/kiwix-js/badge)](https://www.codefactor.io/repository/github/kiwix/kiwix-js)\n[![Licence: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n[![Kiwix for Firefox](https://img.shields.io/amo/v/kiwix-offline?label=Kiwix%20for%20Firefox\u0026logo=firefoxbrowser\u0026logoColor=whitesmoke)](https://addons.mozilla.org/fr/firefox/addon/kiwix-offline/)\n[![Kiwix for Chrome](https://img.shields.io/chrome-web-store/v/donaljnlmapmngakoipdmehbfcioahhk?label=Kiwix%20for%20Chrome\u0026logo=googlechrome\u0026logoColor=whitesmoke)](https://chrome.google.com/webstore/detail/kiwix/donaljnlmapmngakoipdmehbfcioahhk)\n[![Kiwix for Edge](https://img.shields.io/badge/dynamic/json?label=Kiwix%20for%20Edge\u0026logo=microsoftedge\u0026logoColor=whitesmoke\u0026prefix=v\u0026query=%24.version\u0026url=https%3A%2F%2Fmicrosoftedge.microsoft.com%2Faddons%2Fgetproductdetailsbycrxid%2Fjlepddlenlljlnnhjinfaciabanbnjbp)](https://microsoftedge.microsoft.com/addons/detail/kiwix/jlepddlenlljlnnhjinfaciabanbnjbp)\n\n## Usage\n\nInstall \"Kiwix JS\" from your browser's add-on store. This is the best way to get the extension, because it will be kept up to date automatically. If\nyou would rather not use a store, you can get a file-based version of the extension from http://download.kiwix.org/release/browsers/ (and follow\n[instructions below](#installing-signed-or-unsigned-extension-files-in-chromium)), but you will have to update this manually.\n\nAlternatively, you can bookmark or install the PWA version from https://browser-extension.kiwix.org/current/ (it will auto-update), or try our dedicated\nPWA version at https://pwa.kiwix.org. To install the PWA (in Chromium browsers), go to Settings -\u003e Apps -\u003e Install this site as an app.\n\nAs mentioned above, the app requires at least one ZIM archive of offline content. You can download one from the in-app library, or else in any browser go to\nhttps://library.kiwix.org (this has a nice, graphical interface and a preview of each ZIM archive) or from https://download.kiwix.org/zim/ (a more basic list of archives).\nYou have to download these separately, store them in your filesystem, and manually select them after starting the application (or you can drag-and-drop one into the app).\n\n**Zimit-based archives** (available from the \"zimit\" directory on https://download.kiwix.org/zim/, or made yourself with [youzim.it](https://youzim.it/)), are\nfully compatible with this reader. For the best experience, you will need a modern browser and to allow the app to *run in [ServiceWorker mode](#some-technical-details) as an offline-first PWA*\n([see below](#some-technical-details) for an explanation of what this means). If the app is running in any other mode, then only static content will be\nviewable (if at all). Our sister app https://pwa.kiwix.org has some further support for Zimit archives in older browsers.\n\n## Security\n\nBe sure to get your ZIM archives only from a secure source, such as the official Kiwix library. This is because ZIM archives can run dynamic code in your browser. While\nwe do our best to sandbox the ZIM's content, a determined malicious ZIM could remove the sandbox and redirect the iframe to, say, a phishing Web site. For this reason\nwe now show a Security Warning when you open a ZIM with dynamic content in ServiceWorker mode for the first time. If you do not trust the source of the ZIM, and wish to\nbrowser static content safely, then open the ZIM first in Restricted Mode before deciding whether to switch to ServiceWorker Mode.\n\n## Compatibility\n\nSince the app is written in HTML/JavaScript, it should work in most recent browser engines and many older ones too, depending on the Content\nInjection mode supported by the specific browser engine. Archives containing dynamic content (most non-Wikimedia archives) work better\nin ServiceWorker mode ([see below](#some-technical-details)), but unfortunately this is not available in many older browsers. If you wish to read such archives, we\nwould suggest that you upgrade to a browser that supports Service Workers (Chrome 58+, Firefox 61+ [not ESR versions], Edge 17+, Safari 11.3+).\n\n### Officially supported platforms\n\n- \u003cimg src=\"images/firefoxbrowser-color.svg\" width=\"20\" /\u003e Mozilla Firefox \u003e=56 (as an extension): [Mozilla Add-ons Store](https://addons.mozilla.org/firefox/addon/kiwix-offline/)\n    + Firefox 52-56 and ESR version 58: Limited support (Restricted mode only)\n- Chromium / Chrome / Edge \u003e= 88 (as a Manifest V3 extension):\n    + \u003cimg src=\"images/googlechrome-color.svg\" width=\"20\" /\u003e Google Chrome \u003e=88: [Chrome Web Store](https://chrome.google.com/webstore/detail/kiwix/donaljnlmapmngakoipdmehbfcioahhk)\n    + \u003cimg src=\"images/microsoftedge-color.svg\" width=\"20\" /\u003e Microsoft Edge \u003e=88: [Edge Add-ons Store](https://microsoftedge.microsoft.com/addons/detail/kiwix/jlepddlenlljlnnhjinfaciabanbnjbp)\n- Chromium / Chrome / Edge 58-87 (as a Manifest V2 extension): use the MV2 zip from the `chrome` or `edge` directory in https://download.kiwix.org/release/browsers/, and follow [instructions below](#installing-signed-or-unsigned-extension-files-in-chromium)\n- \u003cimg src=\"images/safari-color.svg\" width=\"20\" /\u003e Safari \u003e=11.3 on macOS or iOS: no extension available, but use https://browser-extension.kiwix.org and install to Home screen; for a more fully featured PWA, use https://pwa.kiwix.org\n- \u003cimg src=\"images/electron-color.svg\" width=\"27\" /\u003e Electron \u003e=1.8.0 and NWJS \u003e=0.14.7 (as an application for Linux and Windows): https://kiwix.github.io/kiwix-js-pwa/app\n- \u003cimg src=\"images/microsoftwindows-color.svg\" width=\"20\" /\u003e Universal Windows Platform (UWP) \u003e=10.0.10240 (as an HTML/JS application): [Microsoft Store](https://www.microsoft.com/store/apps/9P8SLZ4J979J)\n- \u003cimg src=\"images/ubuntu-color.png\" width=\"20\" /\u003e Ubuntu Touch (as an application): [Ubuntu OpenStore](https://open-store.io/app/kiwix)\n\n### Deprecated platforms\n\nThese platforms/browsers are deprecated. We still partially test against them, and we'll try to keep compatibility as long as it's not too complicated:\n\n- Firefox OS \u003e=1.2: needs to be installed manually on the device with WebIDE\n- Microsoft Edge Legacy \u003e=17: no extension available, but bookmark https://browser-extension.kiwix.org or https://pwa.kiwix.org\n- Microsoft Edge Legacy 15-16: needs to run a bundled version of the source code in Restricted mode only\n- Microsoft Internet Explorer 11: needs to run a bundled version of the source code in Restricted mode only\n\n**_You can build a bundled version by running `npm install` and `npm run build` in the root directory of this repo._** Alternatively, a bundled version is served\nas a web app for testing from https://kiwix.github.io/kiwix-js/dist/ (also available on the `gh-pages` branch of this repo, under `/dist`). \n\n### Installing signed or unsigned extension files in Chromium\n\nIf you need to install Chromium (Chrome or Edge) extension from a file instead of from a Store, e.g. if your browser doesn't support Manifest V3, then you will need to download a\nsigned or unsigned CRX or ZIP file from a relevant directory in https://download.kiwix.org/release/browsers/, or else a nightly version from https://download.kiwix.org/nightly/.\nFiles with `mv2` in their filename are in the legacy Manifest V2 format.\n\nTo install your CRX or ZIP, open the extension management page in your browser, e.g. chrome://extensions/ or edge://extensions/, and turn on Developer mode. Now, you should be\nable to drag and drop the ZIP file into this page. Verify the extension is showing in the management page.\n\nFiles that we deliver with a `.crx` file extension are files that have been validated by the Edge or Chrome Stores, and you should be able to install these as \"first-class\" apps.\nZIP files provided in https://download.kiwix.org/release/browsers/, or the ones labelled `signed` in nightly, are actually signed CRX files that have been renamed with a `.zip`\nextension to facilitate downloading and installing them in Chromium browsers. Although signed, you cannot install them as CRX files, because they have not been validated by the\nChrome or Edge Stores. **_For this reason, the browser will periodically ask you if you want to turn off developer-mode extensions. Just choose \"ask again in two weeks\"._**\n\nIf drag-and-drop is difficult, you can instead unzip the extension ZIP into a folder, and note the location. Then select \"Load unpacked\" and choose  the folder that contains the\nunzipped extension. To unzip the MV2 files with a utility like 7Zip, you will need to change the extension name to `.crx`. On Linux, `unzip` can read them without changing the filename.\n\n## Some technical details\n\nTechnically, after reading an article from a ZIM file, it is necessary to \"inject\" the dependencies (images, css, etc). For compatibility reasons,\nthere are two main ways of doing this:\n\n- \"ServiceWorker\" mode (the default) uses a Service Worker to catch any HTTP request the page may send and reply with content read from\nthe ZIM file. It is a generic and clean way of serving content to the browser. It works in any recent browser, but not in older ones.\nService Workers are currently disabled by Mozilla in Firefox extensions, and in Chromium extensions active content is severely restricted\nfor security reasons. In both cases we offer a functional workaround (an offline-first PWA version) as a substitute within the extension;\n- \"ServiceWorkerLocal\" mode is a restricted ServiceWorker mode that is available only in Chromium extensions running fully locally. Chromium\nextensions running locally block (by design) a lot of dynamic content such as inline JavaScript and `eval`, which means this mode won't work\nwith some modern dynamic content, and in particular, it won't work with Zimit-based archives (if you open one of these in this mode, you\nwill be thrown back to Restricted mode in order to view static content). However, this mode is useful if you cannot access the offline-first PWA,\nand should work with most official Kiwix ZIM archives;\n- \"Restricted\" mode prevents running attached scripts in the iframe, and so is useful for checking the contents of a ZIM before deciding it is safe\nto run. This mode also works in browsers that do not support Service Workers. It parses the DOM to find the HTML tags of the dependencies and\nmodifies them to point to content we extract from the ZIM. This mode is compatible with any browser, but because it cannot run JavaScript\ninside the ZIM file, does not work well (if at all) with ZIMs that depend on dynamic content. If you open a dynamic (including Zimit) archive\nin this mode (or if you are thrown into the mode due to another incompatibility), then we will do our best to display static content, but much\nfunctionality is likely to be broken. However, Mediawiki-based content (e.g. Wikipedia) works fine in this mode.\n\nYou can switch between these content injection modes in Configuration, but if your browser supports ServiceWorker mode as an offline-first PWA,\nyou are strongly advised to remain in this mode (unless you wish to check the safety of a ZIM before running it -- the UI will ask you if you\nwish to do this when you first open a new ZIM).\n\n### File access and other limitations\n\nYou can only re-open an archive automatically if your browser supports the File System Access API and allows you to grant permanent access permission.\nIn practice, this currently means Chromium browsers (Chrome, Edge, etc.) with a version number of 122 or higher. If that is the case, you will see a\npopup asking you whether you wish to grant access \"on every visit\" (this will appear only after the second or third time that you have picked an archive\nor folder). If you grant this permanent permission, then the browser will (optionally) re-open the last-visited archive when you open the app.\n\nIn other cases, your browser may fall back to using the `webkitdirectory` property of the File API, which allows you to re-open a folder or directory of\nZIMs with a quick permission prompt. Another alternative is to drag-and-drop a ZIM file into the app.\n\nThere are [versions of this app](https://kiwix.github.io/kiwix-js-pwa/app) that have experimental support for the Origin Private File System, or that use\nframeworks like Electron, which do have the capability of remembering the chosen archive between app launches.\n\nThe app has fast title search, and slower full-text search for ZIM archives that have a full-text index, thanks to the\n[openzim/javascript-libzim](https://github.com/openzim/javascript-libzim) project. Currently, full-text searching only works in browsers\nthat support [Atomic Operations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Atomics), which means\nrecent desktop versions of Chromium and Firefox. There is also support in Safari on iOS 15+.\n\n## Licence\n\nThis application is released under the GPL v3 licence. See http://www.gnu.org/licenses/ or the included LICENSE-GPLv3.txt file\nThe source code can be found at https://github.com/kiwix/kiwix-js.\n\n## Contributing\n\nKiwix JS is an open-source project. We encourage individuals with experience of HTML and JavaScript development to contribute to the documentation and code in this repository.\n\nTo report a bug, read our [REPORT_BUG](REPORT_BUG.md) guide.\n\nFor code contributions, read our [CONTRIBUTING](CONTRIBUTING.md) guide.\n\nTo get to know the Kiwix project better, please familiarize yourself with the content on https://www.kiwix.org. There is also a Kiwix [Slack](https://join.slack.com/t/kiwixoffline/shared_invite/zt-19s7tsi68-xlgHdmDr5c6MJ7uFmJuBkg) group which you can join.\n\nWe also have a [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md): everybody is expected to follow it.\n\n## Public releases and nightly builds\n\nThe browser extensions are distributed through the stores of each vendor (see links above). But the packages are also saved in https://download.kiwix.org/release/browsers/ if necessary.\n\nSome nightly builds are generated, and should only be used for testing purpose: https://download.kiwix.org/nightly/.\n\nThere is a test implementation of the latest code at https://kiwix.github.io/kiwix-js/ (unbundled: needs a modern browser that supports native ES6 modules), and a bundled version for any\nHTML5 browser (\u003e=IE11) at https://kiwix.github.io/kiwix-js/dist/, but these implementations are used for development, and may be buggy, experimental or unstable. A stable PWA version for\nuse in the browser extensions is available from https://browser-extension.kiwix.org/current/.\n\n## Previous versions\n\nThe first versions of this application were originally part of the Evopedia project: http://www.evopedia.info (discontinued). There was an \"articles nearby\" feature, that was able to find articles around your location. It has been deleted from the source code with everything related to Evopedia (but still in git history in versions\u003c=2.0.0).\n\nThese first versions were targeting Firefox OS (discontinued too: we're not lucky ;-) ).\n\nSee [CHANGELOG.md](CHANGELOG.md) for details of previous versions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwix%2Fkiwix-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiwix%2Fkiwix-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwix%2Fkiwix-js/lists"}