maplibre gl usgs lidar

The Problem

Clients that need to explore USGS 3DEP LiDAR point clouds often resort to downloading massive COPC files and writing custom viewers. The manual workflow is slow, error‑prone, and forces each team to re‑implement map interaction, search, and streaming logic.

What This Does

maplibre-gl-usgs-lidar delivers a ready‑made MapLibre GL plugin that searches the USGS STAC catalog, draws item footprints, and streams COPC point clouds directly on the map. The core implementation lives in src/lib/core/UsgsLidarControl.ts (≈830 LOC) and its React wrapper src/lib/core/UsgsLidarControlReact.tsx. UI construction is in src/lib/gui/PanelBuilder.ts. Example entry points are examples/basic/main.ts (vanilla) and examples/react/main.tsx (React). All TypeScript source is compiled via Vite (vite.config.ts) and can be containerised with the provided Dockerfile.

How It Is Wired

Execution starts at the HTML entry points (examples/basic/index.html or examples/react/index.html). The scripts import the control:

Vanilla – examples/basic/main.ts imports src/index.ts, which re‑exports UsgsLidarControl.
React – examples/react/main.tsx renders <UsgsLidarControlReact> imported from src/lib/core/UsgsLidarControlReact.tsx.

Both paths instantiate UsgsLidarControl. Its constructor registers event listeners (_setupEventListeners) and creates UI components via PanelBuilder. The most‑used internal functions are:

setState – called from 22 places, propagates UI and map updates.
_emit – invoked 8 times, dispatches custom events (searchcomplete, loadcomplete).
getState – read from 8 locations, provides the current control state.

The control’s search flow (searchByBbox) calls StacSearcher.search, then setState and _emitWithData. Footprint rendering is handled by FootprintLayer (src/lib/results/FootprintLayer.ts). The plugin’s hub modules are:

Module	Ca (importers)	Ce (imports)	Instability
`src/index`	2	6	0.75
`src/lib/core/UsgsLidarControl`	3	5	0.63
`src/lib/core/types`	8	0	0
`src/lib/gui/PanelBuilder`	2	2	0.5

No circular dependencies were detected. The largest blast radius belongs to setState and _emit, because any change there ripples through >20 functions across the UI and map layers.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/maplibre-gl-usgs-lidar
cd maplibre-gl-usgs-lidar

# Install dependencies (npm is the declared manager)
npm ci

# Run the vanilla example locally
npm run dev   # Vite dev server serves examples/basic

# Or build and run the Docker image
docker build -t maplibre-gl-usgs-lidar .
docker run -p 8080:80 maplibre-gl-usgs-lidar

The Dockerfile serves the built assets with an Nginx front‑end. No environment variables are required; the plugin contacts the public USGS STAC endpoint directly.

Real‑World Use

A municipal GIS team can embed the React component in an existing dashboard, passing the MapLibre map instance. The control lets analysts draw a bounding box, automatically fetches matching LiDAR tiles, and streams them into the map without pre‑loading gigabytes of data, keeping the web app responsive.

Code Health & Issues

HIGH – Pin third‑party GitHub Actions to commit SHAs (.github/workflows/*).
MEDIUM – Declare least‑privilege permissions for GITHUB_TOKEN (publish.yml).
MEDIUM – Add Dependabot or Renovate (.github/dependabot.yml).
MEDIUM – Pin Docker base images by digest (Dockerfile).
MEDIUM – Add a dependency‑vulnerability scan step in CI.
MEDIUM – Set persist-credentials: false on checkout (deploy-pages.yml).
MEDIUM – Run container as non‑root (Dockerfile).
LOW – Define timeout-minutes for workflow jobs (deploy-pages.yml).

Static analysis also reported duplicated 6‑line blocks across seven files and two oversized modules (UsgsLidarControl.ts, PanelBuilder.ts), suggesting a refactor to extract shared helpers and split responsibilities.

The Bottom Line

The repository offers a functional, TypeScript‑based viewer that eliminates the need to build a LiDAR search UI from scratch. It is well‑structured but suffers from duplicated code, large monolithic files, and several CI‑related hardening gaps. Teams comfortable with MapLibre and React will find it immediately useful; a modest cleanup and security tightening will make it production‑ready.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

44 files

TypeScript23
YAML4
HTML4
JSON4
TSX2
CSS2

ReactDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src<br/>18 modules"] g1["(root)<br/>3 modules"] g2["examples<br/>2 modules"] g3["tests<br/>2 modules"] g2 -->|3| g0 g3 -->|1| g0

Module dependencies

The 10 most depended-upon modules of 25, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_lib_core_types["types"] n1_rc_lib_core_UsgsLidarControl["UsgsLidarControl"] n2_src_lib_stac_StacSearcher["StacSearcher"] n3_src_lib_utils_index["index"] n4_src_index["index"] n5_src_lib_gui_PanelBuilder["PanelBuilder"] n6_c_lib_results_FootprintLayer["FootprintLayer"] n7_src_react["react"] n8_b_core_UsgsLidarControlReact["UsgsLidarControlReact"] n9_apters_UsgsLidarLayerAdapter["UsgsLidarLayerAdapter"] n4_src_index --> n1_rc_lib_core_UsgsLidarControl n4_src_index --> n0_src_lib_core_types n4_src_index --> n3_src_lib_utils_index n9_apters_UsgsLidarLayerAdapter --> n1_rc_lib_core_UsgsLidarControl n1_rc_lib_core_UsgsLidarControl --> n0_src_lib_core_types n1_rc_lib_core_UsgsLidarControl --> n2_src_lib_stac_StacSearcher n1_rc_lib_core_UsgsLidarControl --> n6_c_lib_results_FootprintLayer n1_rc_lib_core_UsgsLidarControl --> n5_src_lib_gui_PanelBuilder n1_rc_lib_core_UsgsLidarControl --> n3_src_lib_utils_index n8_b_core_UsgsLidarControlReact --> n0_src_lib_core_types n8_b_core_UsgsLidarControlReact --> n1_rc_lib_core_UsgsLidarControl n5_src_lib_gui_PanelBuilder --> n0_src_lib_core_types n5_src_lib_gui_PanelBuilder --> n3_src_lib_utils_index n6_c_lib_results_FootprintLayer --> n0_src_lib_core_types n2_src_lib_stac_StacSearcher --> n0_src_lib_core_types n7_src_react --> n8_b_core_UsgsLidarControlReact n7_src_react --> n0_src_lib_core_types

Dependencies

15 of 24 declared dependencies are a major version behind. Resolved 24 of 24 against the registry.

Package	Declared	Latest	Behind
`jsdom`	^25.0.0	30.0.1	5 major
`@types/node`	^22.0.0	26.2.0	4 major
`maplibre-gl`	>=3.0.0	6.4.0	3 major
`@vitejs/plugin-react`	^4.3.0	6.0.5	2 major
`@vitest/coverage-v8`	^2.1.0	4.1.10	2 major
`@vitest/ui`	^2.1.0	4.1.10	2 major
`typescript`	^5.7.0	7.0.2	2 major
`vite`	^6.0.0	8.2.1	2 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5, docker/build-push-action@v6

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/publish.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:20-alpine, nginx:alpine

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/deploy-pages.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/deploy-pages.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.