@lonnygomes/ol-zipped-source

This OpenLayers module allows you to serve local map tiles directly from a zip file, enabling offline use cases such as progressive web apps (PWAs) or desktop applications.

How It Works

This package provides a custom OpenLayers tile source (ZippedXYZ) that reads tiles from a zip archive. The zip file is loaded once, and tiles are fetched from it as needed, using a special URL format.

URL Format

To use tiles from a zip file, specify the source URL in the following format:

• The URL must start with zip://
• After the prefix, provide the path to your zip file (relative or absolute)
• After the zip file path, specify the internal path template for tiles, using {z}, {x}, {y} placeholders and the file extension

Example: zip://./db/tiles.zip/tiles/{z}/{x}/{y}.jpg

This means:

• The zip file is at ./db/tiles.zip
• Inside the zip, tiles are stored under tiles/ with the standard {z}/{x}/{y}.jpg structure

Installation

Install via npm:

npm install @lonnygomes/ol-zipped-source

Usage Example

import './style.css';
import { Map, View } from 'ol';
import TileLayer from 'ol/layer/Tile';
import { ZippedXYZ } from '@lonnygomes/ol-zipped-source';

const map = new Map({
  target: 'map',
  layers: [
    new TileLayer({
      source: new ZippedXYZ({
        url: 'zip://./db/tiles.zip/tiles/{z}/{x}/{y}.jpg'
        // You can also pass other ol/source/XYZ options here
      }),
    }),
  ],
  view: new View({
    center: [0, 0],
    zoom: 2,
  }),
});

Example CSS

html,
body {
  margin: 0;
  height: 100%;
}
#map {
  position: absolute;
  top: 0;
  bottom: 0;
  width: 100%;
}

Notes

• The zip file must be accessible via HTTP(S) or from the local filesystem in an Electron or similar environment.
• The internal structure of the zip must match the {z}/{x}/{y}.ext pattern.
• The ZippedXYZ source accepts all standard ol/source/XYZ options.
• If the zip file or tile is missing, errors will be logged to the console.

Advanced

You can customize the tile class or pass additional options using the tileClass and tileOptions parameters. See the source code for details.You can customize the tile class or pass additional options using the tileClass and tileOptions parameters. See the source code for details.