Skip to main content

​
Install the package

npm install @ngageoint/geopackage
The package targets Node.js 12 and later, and all modern browsers.

​
Node.js setup

​
Import the library

You can use either CommonJS require or ES module import: 
const {
  setCanvasKitWasmLocateFile,
  GeoPackageManager,
  Canvas,
} = require('@ngageoint/geopackage');

​
Configure the CanvasKit WASM file

In Node.js, tile and image rendering is powered by CanvasKit — a WebAssembly build of the Skia graphics library. Before calling GeoPackageManager.open or GeoPackageManager.create, you must tell the library where to find canvaskit.wasm. 
setCanvasKitWasmLocateFile(
  file => `${__dirname}/node_modules/@ngageoint/geopackage/dist/canvaskit/` + file
);
The WASM file is bundled with the package at dist/canvaskit/canvaskit.wasm. If you bundle your application or deploy to a non-standard directory, copy that directory to your output path and update the string above to match.
setCanvasKitWasmLocateFile must be called before the first call to GeoPackageManager.open or GeoPackageManager.create. Calling it afterward has no effect because the WASM module is only initialized once.

​
Full Node.js example

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

setCanvasKitWasmLocateFile(
  file => `${__dirname}/node_modules/@ngageoint/geopackage/dist/canvaskit/` + file
);

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

​
Browser setup

​
Use the pre-built bundle

The package ships a UMD browser bundle at dist/geopackage.min.js. Add it to your HTML with a <script> tag. This exposes a window.GeoPackage global that contains all exported classes and functions. 
<script src="/path/to/geopackage.min.js"></script>
You can find the bundle at: 
node_modules/@ngageoint/geopackage/dist/geopackage.min.js
Copy it to your public/static directory, or configure your build tool to serve it.

​
Configure the sql.js WASM file

In the browser, SQLite access is provided by sql.js (compiled to WebAssembly). You must tell the library where to load sql-wasm.wasm from before opening a GeoPackage. 
const { setSqljsWasmLocateFile } = window.GeoPackage;

// Serve sql-wasm.wasm from your /public directory.
setSqljsWasmLocateFile(file => '/public/' + file);
By default the library tries to load sql-wasm.wasm from the root of the current server. Copy the file from: 
node_modules/rtree-sql.js/dist/sql-wasm.wasm
to your public directory (e.g. public/sql-wasm.wasm), then call setSqljsWasmLocateFile with the matching path prefix.
setSqljsWasmLocateFile must be called before the first GeoPackageManager.open call. If the browser cannot find the WASM file, the library will throw an error when it tries to open or create a GeoPackage.

​
Destructure from the global

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

​
Web Worker setup

You can run GeoPackage operations inside a Web Worker to keep the main thread responsive. Import the bundle with importScripts and configure sql.js the same way as in the main thread: 
// worker.js
self.importScripts('/path/to/geopackage.min.js');

const { GeoPackageManager, setSqljsWasmLocateFile } = GeoPackage;

setSqljsWasmLocateFile(file => '/public/' + file);

onmessage = function (e) {
  if (e.data.type === 'load') {
    GeoPackageManager.open(e.data.file).then(gp => {
      self.gp = gp;
    });
  } else if (e.data.type === 'close') {
    self.gp.close();
  }
};
See the Web Worker guide for a complete example including tile retrieval and GeoJSON export.

​
TypeScript

Type definitions are bundled with the package — no separate @types/geopackage package is needed. 
// package.json (excerpt)
{
  "main":  "dist/index.js",
  "types": "dist/index.d.ts"
}
All public classes, methods, and interfaces are fully typed. Import them directly: 
import {
  GeoPackageManager,
  GeoPackage,
  FeatureDao,
  TileDao,
  BoundingBox,
} from '@ngageoint/geopackage';

​
Dependencies

​
Required dependencies

All required runtime dependencies are installed automatically with the package.
PackagePurpose
@ngageoint/projections-jsCoordinate reference system support
@ngageoint/simple-features-jsCore geometry types
@ngageoint/simple-features-geojson-jsGeoJSON import/export
rtree-sql.jsSQL.js with RTree extension (browser SQLite)

​
Optional dependencies

The following packages are listed as optionalDependencies. They are not required for core functionality and will not be installed unless your environment resolves optional deps.
PackagePurpose
better-sqlite3Faster native SQLite adapter for Node.js (falls back to sql.js if absent)
chalkColoured output in the CLI tool
inquirerInteractive prompts in the CLI tool
If you want maximum read/write performance in Node.js, install better-sqlite3 explicitly. It is a native addon and requires a C++ build toolchain:
npm install better-sqlite3

Build docs developers (and LLMs) love

Get started for freeTalk to us