GPXParser.js

Common errors

• ReferenceError: document is not defined

  cause Attempting to run gpxparser in a Node.js environment without proper DOM polyfills. This was a common issue before v3.0.5.
  fix Ensure you are using `gpxparser` v3.0.5 or newer, which bundles necessary polyfills. If not, upgrade or manually provide a DOM polyfill like `jsdom`.

• TypeError: gpx.parse is not a function

  cause The `GPXParser` object was not correctly instantiated or imported. This often happens with incorrect CommonJS `require` or ESM `import` syntax, or if the global `GPXParser` variable is not set up correctly in a browser.
  fix For ESM/TypeScript: `import GPXParser from 'gpxparser';` For CommonJS: `const GPXParser = require('gpxparser');` Then, `const gpx = new GPXParser();`.

• Cannot read properties of undefined (reading 'tracks')

  cause This error occurs when attempting to access properties like `gpx.tracks` or `gpx.waypoints` before the `parse()` method has been successfully called, or if the provided GPX string is malformed/empty and parsing failed to populate these properties.
  fix Always call `gpx.parse(gpxString)` with a valid GPX XML string before attempting to access parsed data properties. Add error handling around `parse()` if the input string might be invalid.

• TS2305: Module '"gpxparser"' has no exported member 'GPXParser'. Did you mean to use 'import GPXParser from "gpxparser"' instead?

  cause Attempting to use a named import (`import { GPXParser }`) for a package that provides a default export.
  fix Change the import statement to use the default import syntax: `import GPXParser from 'gpxparser';`.

Warnings

• breaking Version 3.0.0 introduced significant changes, likely with breaking API modifications. Users upgrading from v2.x should consult the changelog for specific migration steps.
  Fix: Review the official release notes and migration guides for gpxparser v3 to adapt your code. Re-test all GPX parsing and data access logic.
• gotcha Prior to v3.0.5, running GPXParser in Node.js environments required manual polyfills for DOM-related functions (e.g., XMLHttpRequest, DOMParser). Without these, parsing would fail.
  Fix: Upgrade to v3.0.5 or newer, which includes `jsdom-nogyp` as a dependency to provide these polyfills automatically. If upgrading isn't possible, manually include a DOM polyfill library.
• gotcha The package size was reduced in v3.0.8 by removing documentation and demo files directly from the npm package. These resources are now only available on the GitHub repository.
  Fix: Access documentation and demos directly from the project's GitHub repository (github.com/Luuka/GPXParser.js) rather than looking for them in `node_modules`.
• gotcha While v3.0.8 adds TypeScript support, incorrect import statements (e.g., named import for a default export) can lead to compilation errors or runtime issues.
  Fix: Always use `import GPXParser from 'gpxparser';` for ESM and TypeScript, as GPXParser is a default export.

Install

• npm install gpxparser npm
• yarn add gpxparser yarn
• pnpm add gpxparser pnpm

Imports

• GPXParser
  wrong:

  import { GPXParser } from 'gpxparser';

  correct:

  import GPXParser from 'gpxparser';

  The library exports GPXParser as its default export for ESM and TypeScript usage since v3.0.8.
• GPXParser

  const GPXParser = require('gpxparser');

  CommonJS import pattern for Node.js environments.
• GPXParser (browser global)

  <script src="./js/GPXParser.js"></script>
  // GPXParser is then available globally

  When included directly via a <script> tag in a browser, GPXParser becomes a global variable.

Quickstart

This quickstart demonstrates how to instantiate GPXParser, parse a sample GPX string, access its metadata, tracks, and waypoints, and export the processed data to GeoJSON.

import GPXParser from 'gpxparser';

// A minimal GPX string for demonstration
const gpxString = `<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="GPXParser.js">
  <metadata>
    <name>Sample Track</name>
    <desc>A short sample track by GPXParser.js</desc>
    <author>
      <name>Acme Corp</name>
    </author>
    <time>2023-01-01T12:00:00Z</time>
  </metadata>
  <trk>
    <name>Morning Walk</name>
    <trkseg>
      <trkpt lat="34.0522" lon="-118.2437"><ele>100</ele><time>2023-01-01T12:00:00Z</time></trkpt>
      <trkpt lat="34.0535" lon="-118.2500"><ele>110</ele><time>2023-01-01T12:05:00Z</time></trkpt>
      <trkpt lat="34.0548" lon="-118.2563"><ele>105</ele><time>2023-01-01T12:10:00Z</time></trkpt>
    </trkseg>
  </trk>
  <wpt lat="34.0500" lon="-118.2400"><name>Starting Point</name></wpt>
</gpx>`;

const gpx = new GPXParser();
gpx.parse(gpxString);

console.log('GPX Metadata Name:', gpx.metadata.name);
console.log('Total Tracks Found:', gpx.tracks.length);
if (gpx.tracks.length > 0) {
  console.log('First Track Name:', gpx.tracks[0].name);
  console.log('First Track Total Distance (meters):', gpx.tracks[0].distance.total);
  console.log('First Track Max Elevation (meters):', gpx.tracks[0].elevation.max);
}

console.log('Total Waypoints Found:', gpx.waypoints.length);
if (gpx.waypoints.length > 0) {
  console.log('First Waypoint Name:', gpx.waypoints[0].name);
}

// Export parsed GPX data to GeoJSON format
const geoJSON = gpx.toGeoJSON();
console.log('GeoJSON Output:', JSON.stringify(geoJSON, null, 2));