A TypeScript implementation of ESRI Shapefiles, in browsers or NodeJS.
- Dependency-free and lightweight — the bundle is approximately 23 KB (minified, ~8 KB gzipped) with no runtime dependencies
- Supports legacy and current (.CPG-file) DBF codepages, including DOS OEM, Windows (ANSI), ISO-8859, Mac, and CJK (Shift-JIS, GBK, Big5, EUC-KR) encodings
- Supports GeoJSON and WKT (Well Known Text) serialization
- Node.js usage
- Browser usage
- Reading features (geometry + attributes)
- Reading geometries only (.shp and .shx)
- Reading attributes (.dbf, optionally .cpg) only
- Serialization formats (GeoJSON, WKT)
- Reading from a .zip archive
In Node.js, you can load a shapefile by providing a path to the .shp file. The ShapefileFs class reads the .shp file along with the sibling .shx, .dbf, and .cpg files. The .shx file is required; .dbf and .cpg are optional. If a .cpg file is not found, the reader will attempt to resolve the codepage from the DBF header, falling back to CP-1252.
import { ShapefileFs } from 'ts-shapefile/node';
// Read features (geometry + attributes) from a single path
const reader = await ShapefileFs.fromPath('path/to/myfile.shp');
console.log(`Feature count: ${reader.featureCount}`);
const collection = reader.readFeatureCollection();
collection.features.forEach((feature) => {
console.log(feature.toWkt());
});Geometry-only and attributes-only variants are also available:
import { ShapefileFs } from 'ts-shapefile/node';
// Geometry only (.shp + .shx)
const shpReader = await ShapefileFs.fromPathShp('path/to/myfile.shp');
// Attributes only (.dbf + optional .cpg)
const dbfReader = await ShapefileFs.fromPathDbf('path/to/myfile.dbf');If you already have the file contents in memory (e.g. from a zip stream), you can use the fromArrayBuffers / fromArrayBuffer methods directly from the core package — see the sections below.
In the browser, the API consumes File objects (e.g. from an <input type="file"> element) or raw ArrayBuffers. The whole files will be consumed and parsed, so a size check should be performed before consuming large files.
The sections below use File objects. Each fromFile / fromFiles method has a fromArrayBuffer / fromArrayBuffers counterpart that takes raw ArrayBuffers — useful when you already have the bytes in memory, and also usable in Node.js if needed.
Features can be read one by one, or simply as a whole collection.
const reader = await ShapeFeatureReader.fromFiles(shp, shx, dbf, cpg);
console.log(`Feature count: ${reader.featureCount}`);
console.log(`Number of attributes: ${reader.fields.length}`);
reader.fields.forEach((field) => console.log(` field: ${field.name}(${field.typeName})`));
// Read record by record
for (var i = 0; i < reader.featureCount; i++) {
const feature = reader.readFeature(i);
console.log(feature.toWkt());
}
// Or read the entire collection at once
const collection = reader.readFeatureCollection();
collection.features.forEach((feature) => { ... } );const reader = await ShapeReader.fromFile(shpFile, shxFile);
console.log(`Shape type: ${reader.shapeType}`);
console.log(`Record count: ${reader.recordCount}`);
console.log(`Has Z: ${reader.hasZ}`);
console.log(`Has Z: ${reader.hasM}`);
for (var i = 0; i < reader.recordCount; i++) {
var geom = reader.readGeom(i);
console.log(geom.toWkt());
}Note that if a CPG file is not specifed, the reader will attempt to resolve codepages from the DBF header. If not found, it will fall back to CP-1252
const reader = await DbfReader.fromFile(dbfFile, cpgFile);
console.log(`Encoding: ${reader.encoding}`);
console.log(`Record count: ${reader.recordCount}`);
for (var i = 0; i < reader.recordCount; i++) {
var rec = reader.readRecord(i);
for (var f = 0; f < reader.fields.length; f++) {
console.log(`${reader.fields[f].name}(${reader.fields[f].typeName}) = ${rec[f]}`);
}
}Geometries and features can be serialized to two formats: GeoJSON and WKT (Well Known Text). Both are available on every geometry and feature object.
toGeoJson() returns a GeoJSON geometry object. On ShapeFeature it returns a full GeoJSON Feature with properties; on ShapeFeatureCollection it returns a FeatureCollection.
const reader = await ShapeReader.fromFile(shpFile, shxFile);
for (let i = 0; i < reader.recordCount; i++) {
const geom = reader.readGeom(i);
console.log(JSON.stringify(geom.toGeoJson()));
// {"type":"Point","coordinates":[-155,-154]}
// {"type":"LineString","coordinates":[[-174.45,-156.65],...]}
// {"type":"MultiPolygon","coordinates":[[[[...]]]]}
}
// Features include attributes as properties
const featureReader = await ShapeFeatureReader.fromFiles(shp, shx, dbf, cpg);
const collection = featureReader.readFeatureCollection();
console.log(JSON.stringify(collection.toGeoJson()));
// {"type":"FeatureCollection","features":[...]}toWkt() returns a WKT string. The output follows the ISO SQL/MM convention, appending a Z, M, or ZM suffix to the geometry type when the shapefile carries those dimensions.
const reader = await ShapeReader.fromFile(shpFile, shxFile);
for (let i = 0; i < reader.recordCount; i++) {
const geom = reader.readGeom(i);
console.log(geom.toWkt());
// "POINT (-155 -154)"
// "POINT ZM (-153 -178 1 2)"
// "LINESTRING (-174.45 -156.65, -156.03 -160.44, -146.82 -153.40)"
// "MULTILINESTRING ((...), (...))"
// "POLYGON ((100 60, 100 -40, -100 -40, -100 60, 100 60), (...))"
// "MULTIPOLYGON (((...), (...)), ((...)))"
}ShapeFeature.toWkt() returns the WKT string for the feature's geometry (or null for null geometries). ShapeFeatureCollection.toWkt() returns an array of WKT strings, one per feature.
const collection = reader.readFeatureCollection();
const wktStrings = collection.toWkt(); // Array<string | null>Shapefiles are frequently distributed as .zip archives containing the
.shp, .shx, .dbf, and optionally .cpg files. This library does not
bundle a zip decoder — use whichever library you prefer to extract the
entries, then pass the raw ArrayBuffers to fromArrayBuffers.
For large archives, unzipit is a good choice: it performs random-access decompression, so only the entries you actually read are inflated rather than the entire archive. It works in both browsers and Node.js.
import { ShapeFeatureReader } from 'ts-shapefile';
import { unzip } from 'unzipit';
// `file` is a File from an <input type="file"> element
const { entries } = await unzip(file);
// Helper: find the first entry whose name ends with the given extension
const findByExt = async (ext: string): Promise<ArrayBuffer | undefined> => {
const entry = Object.values(entries).find((e) => e.name.toLowerCase().endsWith(ext));
return entry ? await entry.arrayBuffer() : undefined;
};
const reader = await ShapeFeatureReader.fromArrayBuffers(
await findByExt('.shp'),
await findByExt('.shx'),
await findByExt('.dbf'),
await findByExt('.cpg') // optional
);
const collection = reader.readFeatureCollection();
collection.features.forEach((feature) => {
console.log(feature.toWkt());
});import { readFile } from 'node:fs/promises';
import { ShapeFeatureReader } from 'ts-shapefile';
import { unzip } from 'unzipit';
// Read the .zip file into memory, then let unzipit parse it
const data = await readFile('path/to/archive.zip');
const { entries } = await unzip(data);
const findByExt = async (ext: string): Promise<ArrayBuffer | undefined> => {
const entry = Object.values(entries).find((e) => e.name.toLowerCase().endsWith(ext));
return entry ? await entry.arrayBuffer() : undefined;
};
const reader = await ShapeFeatureReader.fromArrayBuffers(
await findByExt('.shp'),
await findByExt('.shx'),
await findByExt('.dbf'),
await findByExt('.cpg') // optional
);
const collection = reader.readFeatureCollection();
collection.features.forEach((feature) => {
console.log(JSON.stringify(feature.toGeoJson()));
});The examples above assume a single shapefile bundle per archive. If the archive contains multiple bundles, group the entries by basename first and create a reader for each group.