
The map that never released its handlers — three defects inside one effect
The map drew correctly and forgot to let go
The Dogwalk search screen has a map. Every available walker is a point, nearby points collapse into a cluster with a count, and clicking a cluster zooms into that area. It is the part of the app users touch the most: open search, drag the map, apply a filter, click a cluster.
Two things started showing up together, and neither one raised an error. After changing the filter, clicking a cluster moved the zoom somewhere that did not match what was on screen. And the map kept getting heavier as navigation continued — dragging responded worse and worse. Clean console, green suite, no warning.
The tools I use on this project live in the skills store — the first one is free.
The defect lived in a single effect that builds the clustering layer, in React with MapLibre GL. And it was not one defect: it was three stacked in the same place.
Defect one: the cleanup outside the scope
The effect registered two click listeners — one for the cluster circle, one for the individual point — and returned a cleanup function. The detail is where each piece lived:
try {
const handleClusterClick = (ev) => { /* zoom into the cluster area */ };
map.on('click', 'clusters-circles', handleClusterClick);
} catch (err) {
// nothing
}
return () => {
// same function? it does not exist here
map.off('click', 'clusters-circles', handleClusterClick);
};
The cleanup sits outside the try block, so by the time it ran the name handleClusterClick was no longer in scope. Every unmount threw a ReferenceError — and the cleanup body was wrapped in a try/catch whose catch did nothing beyond a comment. The result: no click listener ever left the map. Each unmount left a pair of handlers stuck on layers that had already been destroyed.
Defect two: an anonymous handler cannot be removed
The two cursor listeners — mouseenter and mouseleave, used to swap the cursor on hover — were anonymous functions written straight into the call:
map.on('mouseenter', 'clusters-circles', () => { map.getCanvas().style.cursor = 'pointer'; });
With no stored reference, the cleanup’s map.off had nothing to remove. And in MapLibre, off given a new function is a silent no-op: it compares by reference, finds nothing and stays quiet. That pair only cost a ghost cursor — but it was the same pattern as defect one, in the same block of code.
Defect three: a fresh object in the dependency list
The effect received, among its dependencies, a colors object built inside the component body. React compares dependencies by reference: an object literal recreated on every render is always “different”, so the effect re-ran every time. And re-running, in this case, means removing three layers plus the source and creating everything again.
Measured before the fix: 3 addSource calls across 3 renders. Each rebuild drops styling and forces the rendering engine to reprocess the whole GeoJSON — which is why the map got slow without any request counter noticing.
What the three did together
On their own, each one is annoying. Together they produce the worst kind of bug: a click handler that outlives its layer and closes over stale data. Clicking a cluster after changing the filter fired a handler created with the previous walker list, sending the map to a coordinate that no longer existed in the current viewport. Nothing broke. The map simply lied.
The fix: stored reference, right order, memo by content
Three surgical changes in the same effect, in commit 517645b9:
- All six functions became named and stored in a ref, populated before registration. Cleanup reads from the ref instead of a block-scoped variable — the scope problem stops existing.
- Cleanup now calls
offbeforeremoveLayer. With a live listener pointing at a removed layer, MapLibre fires on a dead object. - The colors object became content-based memoization, and the cluster click callback moved into a “keep the latest” ref — stable identity, effect no longer restarts.
The cleanup catch also stopped being mute: in development it reports which step failed.
The proof and the lesson
eslintwent back to RC=0; before, it reported 2no-undef— the very two names the cleanup tried to use outside their scope. The linter already knew about the bug; nobody was treating that as a build error.- Component tests: 12/12, with three new cases — cleanup removes all six listeners, cleanup removes the three layers and the source, and a re-render with the same data recreates nothing.
- Suite: 3051 tests (was 3048). Build RC=0.
addSource: 1 per render (was 3).
The transferable lesson is about silence, not about maps. Two empty catch blocks turned a scope error into acceptable behaviour: the app kept drawing, so nobody looked. And the cheapest detector — the linter — had been pointing at it all along.
Next step
Sweep the other places that register a listener on a map object with one question: is the function that leaves the same one that entered? Wherever the answer depends on block scope or an inline function, move it into a stored reference. It is a one-question audit, and it catches the whole class.
Related entries
Same project, same ground — the stories connect.
Next step
If this was useful, there is more: I write about the same ground in the other projects, and the store holds the tools I use here.
Done — I will send the next article when it is out.
No spam, one-click unsubscribe. I am also here: Skills store · Portfolio