GPX Mapper
A Node.js CLI tool that converts a directory of GPX files into a static website with an interactive map. Perfect for cycling clubs to publish their frequent routes.
Features
- Interactive Map: Routes displayed on OpenStreetMap vector tiles using MapLibre GL JS
- Responsive Design: Two-pane layout on desktop (sidebar + map), dropdown selector on mobile
- Route Details: Shows distance (km) and elevation gain (m) for each route
- Shareable URLs: Link directly to specific routes
- GPX Downloads: Each route includes a download link to the original GPX file
- Unique Route Colors: Each route gets a distinct color for easy identification
- Static Output: Generates a standalone website that can be hosted anywhere
Installation
``bash
npm install
`
Usage
`bash
npx gpx-mapper [options]
`
$3
| Option | Description | Default |
|--------|-------------|---------|
| -t, --title
<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Site title | "Route Map" |<br />| </code>-V, --version<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Show version number | |<br />| </code>-h, --help<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Show help | |</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br /><h1 class="text-2xl font-bold mt-6 mb-4">Basic usage</h1><br />npx gpx-mapper ./gpx ./dist</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">With custom title</h1><br />npx gpx-mapper ./gpx ./dist --title "EGCC Routes"<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Output Structure</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />dist/<br />├── index.html # Main HTML page<br />├── app.js # Client-side JavaScript<br />├── routes.json # Route data (loaded at runtime)<br />└── gpx/ # Copied GPX files for download<br /> ├── route1.gpx<br /> ├── route2.gpx<br /> └── ...<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Viewing the Generated Site</h2></p><p class="my-3">The generated site must be served via HTTP (not opened directly as a file) because it fetches </code>routes.json<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> at runtime.</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br /><h1 class="text-2xl font-bold mt-6 mb-4">Using npx serve</h1><br />npx serve ./dist</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Or any other static file server</h1><br />python -m http.server 8000 --directory ./dist<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">How It Works</h2></p><p class="my-3">1. <strong>Build Time</strong>: The CLI parses all GPX files in the input directory, extracts route names, coordinates, distances, and elevation data<br />2. <strong>Output</strong>: Generates a static website with the route data stored in </code>routes.json<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />3. <strong>Runtime</strong>: The client-side JavaScript fetches </code>routes.json<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> and renders routes on the map</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">GPX File Requirements</h2></p><p class="my-3">- Standard GPX 1.1 format<br />- Must contain at least one </code><trk><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> (track) with </code><trkpt><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> (track points)<br />- Route name is extracted from </code><name><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> metadata (falls back to filename)<br />- Elevation data (</code><ele><code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">) is optional but enables elevation gain display</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Browser Support</h2></p><p class="my-3">Works in all modern browsers that support:<br />- ES6+ JavaScript<br />- WebGL (for MapLibre GL JS)<br />- Fetch API</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Dependencies</h2></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br />- </code>commander<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> - CLI argument parsing<br />- </code>gpxparser<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> - GPX file parsing<br />- </code>he` - HTML entity decoding</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br />- MapLibre GL JS - Map rendering<br />- OpenFreeMap tiles - Basemap tiles (Positron style)</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">License</h2></p><p class="my-3">MIT</p><p class="my-3"></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div><template id="P:3"></template></div></div></div><script>self.__next_f.push([1,"27:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n28:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^1.2.0\"}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><script>$RC("B:1","S:1")</script></body></html>