Quickstart

Node.js
Browser

Install the package

npm install @ngageoint/geopackage

Import and configure the canvas adapter

In Node.js, the library uses CanvasKit (WebAssembly) for tile rendering. You must tell it where the .wasm file lives before opening any GeoPackage.

const {
  setCanvasKitWasmLocateFile,
  GeoPackageManager,
  GeoPackageTileRetriever,
  Canvas,
  TileUtils,
} = require('@ngageoint/geopackage');

// Point to the canvaskit WASM file bundled with the package.
setCanvasKitWasmLocateFile(
  file => `${__dirname}/node_modules/@ngageoint/geopackage/dist/canvaskit/` + file
);

If you bundle your app with webpack or esbuild, copy the dist/canvaskit/ directory to your output folder and adjust the path accordingly.

Open a GeoPackage file

Pass the path to a .gpkg file. GeoPackageManager.open returns a Promise.

GeoPackageManager.open('/path/to/file.gpkg').then(async (geoPackage) => {
  // work with geoPackage here
});

Or using async/await:

const geoPackage = await GeoPackageManager.open('/path/to/file.gpkg');

List tables

const tileTables    = geoPackage.getTileTables();
const featureTables = geoPackage.getFeatureTables();

console.log('Tile tables:',    tileTables);
console.log('Feature tables:', featureTables);

Query features as GeoJSON

Iterate over every feature in a table as a GeoJSON Feature object. Always call close() on the result set when you are done.

const table = featureTables[0];
const geoJSONResultSet = geoPackage.queryForGeoJSONFeatures(table);

for (const feature of geoJSONResultSet) {
  console.log(feature); // GeoJSON Feature
}
geoJSONResultSet.close();

Get a tile

Retrieve a web-mercator tile at a given x/y/zoom coordinate and convert it to a base-64 PNG string.

const tileDao = geoPackage.getTileDao(tileTables[0]);
const gpr     = new GeoPackageTileRetriever(tileDao);

const x = 0, y = 0, zoom = 0;
const geoPackageTile = await gpr.getTile(x, y, zoom);

// Decode the tile into an image and draw it onto a canvas.
const canvas        = Canvas.create(TileUtils.TILE_PIXELS_DEFAULT, TileUtils.TILE_PIXELS_DEFAULT);
const context       = canvas.getContext('2d');
const geoPackageImage = await geoPackageTile.getGeoPackageImage();

context.drawImage(geoPackageImage.getImage(), 0, 0);
const base64String = canvas.toDataURL('image/png');

// Free CanvasKit memory — required in Node.js.
Canvas.disposeImage(geoPackageImage);
Canvas.disposeCanvas(canvas);

Close the GeoPackage

geoPackage.close();

In Node.js you must call Canvas.disposeImage(image) and Canvas.disposeCanvas(canvas) after you are finished with each image or canvas object. Failing to do so will leak CanvasKit WebAssembly memory.

Add the browser bundle

Include the pre-built UMD bundle in your HTML. This exposes a window.GeoPackage global.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>GeoPackage demo</title>
  <script src="/path/to/geopackage.min.js"></script>
</head>
<body>
  <input id="fileInput" type="file" />
  <script src="./app.js"></script>
</body>
</html>

The bundle is at node_modules/@ngageoint/geopackage/dist/geopackage.min.js. Copy or serve it from a static directory.

Configure the sql.js WASM location

The browser build uses sql.js to read the SQLite database. Call setSqljsWasmLocateFile before opening any GeoPackage so the browser can find sql-wasm.wasm.

const {
  GeoPackageManager,
  Canvas,
  TileUtils,
  GeoPackageTileRetriever,
  setSqljsWasmLocateFile,
} = window.GeoPackage;

// Tell sql.js where to load sql-wasm.wasm from.
// By default it loads from https://yourserver/sql-wasm.wasm.
setSqljsWasmLocateFile(file => '/public/' + file);

Copy sql-wasm.wasm from node_modules/rtree-sql.js/dist/ to your public directory.

Load from a file input

The browser cannot open files by path — read the file into a Uint8Array first, then pass it to GeoPackageManager.open.

document.getElementById('fileInput').addEventListener('change', function () {
  const file       = this.files[0];
  const fileReader = new FileReader();

  fileReader.onload = function () {
    loadByteArray(new Uint8Array(fileReader.result));
  };
  fileReader.readAsArrayBuffer(file);
});

async function loadByteArray(array) {
  const geoPackage = await GeoPackageManager.open(array);

  // list tables
  console.log('Tile tables:',    geoPackage.getTileTables());
  console.log('Feature tables:', geoPackage.getFeatureTables());

  // query features as GeoJSON
  const featureTables   = geoPackage.getFeatureTables();
  const geoJSONResultSet = geoPackage.queryForGeoJSONFeatures(featureTables[0]);
  for (const feature of geoJSONResultSet) {
    console.log(feature);
  }
  geoJSONResultSet.close();

  geoPackage.close();
}

Retrieve and render a tile

const tileTables = geoPackage.getTileTables();
const tileDao    = geoPackage.getTileDao(tileTables[0]);
const gpr        = new GeoPackageTileRetriever(tileDao);

const x = 0, y = 0, zoom = 0;
const geoPackageTile  = await gpr.getTile(x, y, zoom);
const geoPackageImage = await geoPackageTile.getGeoPackageImage();

const canvas  = Canvas.create(TileUtils.TILE_PIXELS_DEFAULT, TileUtils.TILE_PIXELS_DEFAULT);
const context = canvas.getContext('2d');
context.drawImage(geoPackageImage.getImage(), 0, 0);

// Get a data URL to display the tile as an <img> src.
const base64String = canvas.toDataURL('image/png');

Canvas.disposeImage and Canvas.disposeCanvas are still available in the browser but are not strictly required — browser canvas memory is managed by the JavaScript engine.

Memory management (Node.js)

CanvasKit allocates off-heap WebAssembly memory for every image and canvas it creates. The JavaScript garbage collector cannot free this memory automatically, so you must dispose of these objects manually.

// After drawing is complete, release CanvasKit memory.
Canvas.disposeImage(geoPackageImage);  // free a GeoPackageImage
Canvas.disposeCanvas(canvas);          // free a canvas created with Canvas.create()

Forget these calls inside a loop and your Node.js process will grow without bound.

Next steps

Installation

Full setup instructions for Node.js, browser, and Web Workers.

Feature queries

Spatial bounding-box queries, pagination, and attribute filtering.

Tile rendering

Render map tiles, draw feature tiles, and export images.

Web Worker

Run GeoPackage operations off the main thread.

Get Started

Core Concepts

Guides

Extensions

Memory management (Node.js)

Next steps

Installation

Feature queries

Tile rendering

Web Worker

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Extensions

​Memory management (Node.js)

​Next steps

Installation

Feature queries

Tile rendering

Web Worker

Build docs developers (and LLMs) love

Memory management (Node.js)

Next steps