Weiwudi is a service worker for tile cache. It registers map configurations and caches tile images in IndexedDB, so any map library (Leaflet, OpenLayers, etc.) can read tiles through the cached URL template without modification. The project name comes from 魏武帝 (Weiwudi), originally known as 曹操 (Cao Cao), a warlord of the Eastern Han dynasty.
Weiwudi is open-source under the MIT License.
Read this document in Japanese / 日本語で読む
- Service-worker-based tile cache for XYZ and WMTS tile maps
- Automatic tile caching in IndexedDB via a cached URL template
- First-visit proxy activation (
skipWaiting+clients.claim) without a page reload - Per-map cache capacity limit (
cacheMaxBytes) with least-recently-used eviction - Bulk prefetch (
fetchAll) with progress events (proceed/finish/stop) - Works with any map library (Leaflet, OpenLayers, etc.) through the URL template
- Open-source (MIT) with a peer dependency on
workbox-routing
Current release:
1.1.0. This block is the only place in this repository that carries a release version (ADR-0012); everything outside it is written against the 1.0 release. npm:@c4h/weiwudi
# pnpm (recommended)
pnpm add @c4h/weiwudi
# npm
npm install @c4h/weiwudiimport Weiwudi from '@c4h/weiwudi';
// Register the service worker (resolves once the page is controlled,
// from the first visit, without a reload)
await Weiwudi.registerSW('./sw.js', { scope: './' });
// Register an XYZ tile map
const map = await Weiwudi.registerMap('xyz_map', {
type: 'xyz',
width: 10000,
height: 6000,
url: 'http://example.com/{z}/{x}/{y}.jpg',
cacheMaxBytes: 500 * 1024 * 1024 // cache capacity limit in bytes (optional)
});
// Read tiles through the cached URL template
L.tileLayer(map.url).addTo(leafletMap);registerSW resolves only after the service worker controls the current page
(no reload on first visit). If the page cannot be controlled, it rejects with
"Error: Service worker did not control this page within 10000 ms" (e.g. the
page URL is outside the registration scope). cacheMaxBytes limits the total
size of cached tiles for a map and evicts the least-recently-used tiles; omit it
for no capacity limit.
For browser usage without a build tool, load Weiwudi via CDN:
<!-- Weiwudi main library -->
<script src="https://cdn.jsdelivr.net/npm/@c4h/weiwudi@1.1.0/dist/weiwudi.umd.js"></script>For the service worker file:
// In your service worker (sw.js)
importScripts("https://cdn.jsdelivr.net/npm/workbox-routing@7.4.0/build/workbox-routing.prod.umd.min.js");
importScripts("https://cdn.jsdelivr.net/npm/@c4h/weiwudi@1.1.0/dist/weiwudi-sw.umd.js");- API signatures (release-dependent): see
docs/api/
Clone the repository and install dependencies.
git clone https://github.com/code4history/Weiwudi.git
cd Weiwudi
pnpm installStart the development server with hot reload.
pnpm devAccess http://localhost:5173/ in your browser. The demo features:
- Leaflet map with OSM tiles cached via Weiwudi
- Real-time cache statistics (tile count, cache size)
- Fetch all tiles button
- Clear cache functionality
pnpm buildThis generates:
dist/weiwudi.es.js- ES module for modern bundlersdist/weiwudi.umd.js- UMD bundle for browsersdist/weiwudi-sw.es.js- Service worker ES moduledist/weiwudi-sw.umd.js- Service worker UMD bundledist/weiwudi.d.ts- TypeScript type definitions
pnpm run test:unit # Unit tests (Vitest, tests/unit/)
pnpm test # E2E tests (Playwright, tests/e2e/)The unit tests cover the service-worker gateway logic (src/weiwudi_gw_logic.ts): API branching, tile fetching and caching, and the cache size limit.
The E2E tests verify:
- Service Worker registration and activation
- Tile caching behavior
- Cache statistics retrieval
- Cache clearing functionality
Derived from the
enginesfield inpackage.json(ADR-0012: release-dependent).
- Node.js:
>= 20.0.0 - pnpm:
>= 9.0.0(recommended; npm also works)
Weiwudi requires workbox-routing as a peer dependency. Install it alongside:
pnpm add workbox-routingWeiwudi is part of the Maplat ecosystem by Code for History. See the full ecosystem map (8 repositories + product/corporate sites):
📖 Ecosystem Map — (the diagram is currently kept in a private planning repository; the Sister repositories table below is the public substitute)
| Repository | License | npm | Role |
|---|---|---|---|
| Maplat | Apache 2.0 | @maplat/ui |
Main viewer |
| MaplatCore | Apache 2.0 | @maplat/core |
Core library |
| MaplatTin | Apache 2.0 | @maplat/tin |
TIN conversion |
| MaplatTransform | Apache 2.0 | @maplat/transform |
Coordinate transform |
| MaplatEditor | Apache 2.0 | — | Data authoring tool (desktop) |
| Chuci | MIT | @c4h/chuci |
Multimedia swiper & viewer Web Components |
| Quyuan | MIT | @c4h/quyuan |
GeoJSON template engine + multimedia viewer Web Components |
| Weiwudi | MIT | @c4h/weiwudi |
Service Worker for tile cache |
MaplatEditor is the data authoring tool used to create the maps and POIs that the viewers above render. The Maplat ecosystem is end-to-end: author with MaplatEditor, serve with any of the viewer libraries.
MIT License — see LICENSE.
Copyright (c) 2020-2026 Code for History
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.