Architect your ZIM file

This article outlines policies and recommendations for how a ZIM file should be structured to ensure good compatibility and performance with (Kiwix) readers.

Note: This is a work in progress (WiP).

Javascript

Using JavaScript in a ZIM file is perfectly acceptable. However, it’s important to keep in mind that not all environments allow JavaScript execution. Some reader configurations (such as Restricted Mode in Kiwix-JS and Kiwix-PWA) and some browsers may block JavaScript—especially when running fully offline (see https://github.com/openzim/overview/issues/62 for details).

Policy

• Ensure that all JavaScript only loads local (in-ZIM) resources. Never attempt to load external online content.
• Always aim to provide a no-JavaScript fallback. (In some cases, such as warc2zim, this may not be feasible.)
• When possible, make the no-JS fallback first-class citizen. For example, most MediaWiki-based sites work well without JavaScript, so does ZIM created with mwoffliner.
• If a full fallback is not possible:
  • At minimum, display an explanation stating that the ZIM requires JavaScript
  • Ideally, offer some way to access key ZIM content or resources (e.g. a set of static HTML pages providing a list of resources)
• Security is important, avoid doubtful Javascript libraries and frameworks

Additional Recommendations

• Prefer using Axios over the Fetch API, as the Fetch API is known to have compatibility issues with the zim:// protocol used in Kiwix Desktop.
• In general, Fetch, Service Worker, Cache (and in some cases IndexedDB) and OPFS will not work nicely in ZIM readers, developers should avoid it or develop a nice degradation:
  • Most of these API require a secure origin we do not have in readers
  • Some readers are already using a Service Worker, and inception of a Service Worker inside a Service Worker does not work
• To test the ZIM without Javascript, you can:
  • Use kiwix-serve and disable Javascript in your browser
  • Use "Restricted Mode" of Kiwix-JS and Kiwix-PWA