Shapefile.js

When parsing a .zip file:

• If the zip contains only one .shp file, shp() returns a single GeoJSON object.
• If the zip contains multiple .shp files, shp() returns an array of GeoJSON objects.

All returned GeoJSON objects include an extra property fileName, which contains the name of the shapefile minus its extension (e.g., the common part of the filename).

To use Shapefile.js in a browser without a bundler, you can use unpkg to include the standalone script or import it directly into an ESM-based web script.

Standalone script (old fashioned way):

• https://unpkg.com/shpjs@latest/dist/shp.js
• https://unpkg.com/shpjs@latest/dist/shp.min.js

ESM Import:

import shp from 'https://unpkg.com/shpjs@latest/dist/shp.esm.js'

For use in Node.js, Rollup, Webpack, or any environment using ESM modules, install the shpjs package via npm or yarn.

npm install shpjs --save

You can pass a URL directly to the shp function. This works for both a direct .shp file URL or a .zip file URL containing the shapefile.

Example: Loading a .shp file

import shp from 'shpjs';
const geojson = await shp("files/pandr.shp");

Example: Loading a .zip file

import shp from 'shpjs';
const geojson = await shp("files/pandr.zip");

You can pass an object containing the individual components of a shapefile to the shp function. This is useful when you have the files separated.

Object Properties:

• shp: (Required) The .shp file buffer.
• dbf: (Optional) The .dbf file buffer. Required if you want to include attributes.
• prj: (Optional) The .prj file buffer. Required if the file uses a projection that needs conversion to WGS84.
• cpg: (Optional) The .cpg file buffer. Required if the .dbf uses a non-UTF8 encoding.

Example:

const object = {};
object.shp = await fs.readFile('./path/to/file.shp');
object.dbf = await fs.readFile('./path/to/file.dbf');
object.prj = await fs.readFile('./path/to/file.prj');
object.cpg = await fs.readFile('./path/to/file.cpg');

const geojson = await shp(object);

You can pass a binary buffer containing a zip file (which must contain at least one shapefile) to the shp function. Supported types include ArrayBuffer, TypedArray, DataView, and Node.js Buffer.

Example: In Node.js

const data = await fs.readFile('./path/to/shp.zip');
const geojson = await shp(data);

Example: In the Browser (using File API)

const data = await file.arrayBuffer();
const geojson = await shp(data);

The combine function takes two arrays—one for geometries (shp) and one for properties (dbf)—and merges them into a single GeoJSON FeatureCollection.

• shp: An array of geometry objects.
• dbf: An array of property objects. If dbf is not provided or is shorter than shp, empty objects {} are used for the missing properties.

import { combine } from 'shapefile-js';

const geojson = combine([
  [{ type: 'Point', coordinates: [0, 0] }], // shp array
  [{ name: 'Location A' }]                   // dbf array
]);
// Result: { type: 'FeatureCollection', features: [{ type: 'Feature', geometry: ..., properties: { name: 'Location A' } }] }

Use parseZip to manually parse a buffer containing a ZIP archive. It automatically handles .shp, .prj, .dbf, .cpg, and .json files within the archive.

If the ZIP contains .prj files, they are processed using proj4 to handle coordinate transformations. You can provide a whiteList of file extensions to include specific non-standard files from the ZIP.

import { parseZip } from 'shapefile-js';

// buffer is the ArrayBuffer of the zip file
// whiteList is an optional array of extensions to include
const geojson = await parseZip(buffer, ['geojson', 'custom']);

For low-level control, you can use the exported internal parsing functions directly:

• parseShp(shp, prj): Parses a shape buffer. shp should be a DataView or ArrayBuffer. prj can be a string (projection definition) or a proj4 transformed object. If prj is invalid, it defaults to false.
• parseDbf(dbf, cpg): Parses a DBF buffer. dbf should be a DataView or ArrayBuffer. cpg is an optional character encoding file (as a string or buffer).

import { parseShp, parseDbf } from 'shapefile-js';

// Parsing shape
const geometries = await parseShp(shpBuffer, prjString);

// Parsing attributes
const properties = await parseDbf(dbfBuffer, cpgBuffer);