@yboyer/mbtiles

A TypeScript library for reading MBTiles files using better-sqlite3.

Installation

npm install @yboyer/mbtiles

Usage

import { MBTilesReader } from '@yboyer/mbtiles'

const reader = new MBTilesReader('/path/to/file.mbtiles')

// Retrieve a tile
const tile = reader.getTile(z, x, y)
if (tile) {
  console.log(tile.data)    // Buffer
  console.log(tile.headers) // Content-Type, Content-Encoding, ETag, Last-Modified
}

// Retrieve metadata
const info = reader.getInfos()
console.log(info) // { scheme, minzoom, maxzoom, center, bounds, ... }

// Always close the reader when done
reader.close()

API

new MBTilesReader(file, debug?)

Opens an MBTiles SQLite file in read-only mode.

| Parameter | Type | Description | |-----------|-----------|------------------------------------------| | file | string | Path to the .mbtiles file | | debug | boolean | Enable verbose SQLite logging (optional) |

Throws if the file does not exist or cannot be opened as a SQLite database.

close(): void

Closes the underlying SQLite database connection. Always call this when done with the reader.

getTile(z, x, y): GetTileResponse | null

Returns the tile at the given zoom level and coordinates, or null if not found.

The Y coordinate is automatically flipped from XYZ to TMS convention.

Supported tile formats: PNG, JPEG, GIF, WebP, PBF (gzip / deflate compressed).

Response shape:

{
  data: Buffer
  headers: {
    'Content-Type': string
    'Content-Encoding'?: string   // 'gzip' | 'deflate' for PBF tiles
    'Last-Modified': string
    ETag: string
  }
}

getInfos(): Info | null

Returns the metadata stored in the MBTiles file, or null if empty.

The json metadata key is parsed and merged at the top level. minzoom/maxzoom are cast to integers; center/bounds to number arrays.

{
  scheme: string      // defaults to 'xyz'
  minzoom: number
  maxzoom: number
  center: number[]
  bounds: number[]
  [key: string]: unknown
}

MBTilesReader.checkFile(file)

Static helper that opens the file and throws if it is invalid or missing. The connection is closed automatically after the check.

Development

npm run build   # Compile TypeScript
npm run lint    # Lint with Biome

License

ISC