// Reproduce a public GitHub issue or PR in the Mapbox GL JS repo as a minimal focused debug page under `./debug/`. Trigger when the user pastes a GitHub issue/PR URL (github.com/mapbox/mapbox-gl-js/issues/N or /pull/N), or says "repro this issue", "reproduce
| name | repro-issue |
| description | Reproduce a public GitHub issue or PR in the Mapbox GL JS repo as a minimal focused debug page under `./debug/`. Trigger when the user pastes a GitHub issue/PR URL (github.com/mapbox/mapbox-gl-js/issues/N or /pull/N), or says "repro this issue", "reproduce |
Goal: given a link to a public GitHub issue or PR, produce the smallest self-contained debug page at debug/<issue-number>.html that exercises the reported bug. A tired developer should be able to open it, see the bug, and start debugging in under a minute.
Use gh issue view <N> --repo mapbox/mapbox-gl-js --comments (or gh pr view for PRs) to fetch the full body and comments. Do not rely only on the title or first paragraph — triage comments, maintainer replies, and attached code snippets usually contain the actual repro recipe.
Extract:
../dist/mapbox-gl-dev.js build regardless.If the issue is ambiguous, ask one clarifying question before writing code. Do not invent symptoms not reported.
ls debug/<issue-number>.html 2>/dev/null
If a file exists, read it first and ask whether to overwrite or iterate.
Target: one HTML file, debug/<issue-number>.html. No new dependencies. No new assets unless the bug requires a specific image/font/tile set already hosted publicly.
<!DOCTYPE html>
<html>
<head>
<title>#<N>: <one-line summary></title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
<link rel="stylesheet" href="../dist/mapbox-gl.css" />
<style>
body { margin: 0; padding: 0; }
html, body, #map { height: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script src="../dist/mapbox-gl-dev.js"></script>
<script type="module">
import {getAccessToken} from './access_token_generated.js';
mapboxgl.accessToken = getAccessToken();
const map = window.map = new mapboxgl.Map({
container: 'map',
hash: true,
// ...issue-specific config
});
</script>
</body>
</html>
window.map = new mapboxgl.Map({...}) — exposes the map on window for console debugging (map.getStyle(), map.queryRenderedFeatures(...)).hash: true — preserves camera state in URL so reloading keeps the failure view.../dist/mapbox-gl-dev.js — user must run npm run build-dev first; do not use a minified build.access_token_generated.js — shared token file. Never hardcode tokens.mapbox://styles/...) when the bug is about a specific public style.At the top of the <script type="module"> block, add a one-line comment:
// Repro for https://github.com/mapbox/mapbox-gl-js/issues/<N>
// <one-sentence summary of expected vs actual>
This lets future maintainers tie the page back to the issue without re-reading it.
Before writing, ask: what is the minimum the page needs to show the bug? Strip aggressively:
map.on('load', ...) callback unless sources/layers must be added imperatively.If the issue's sample code is already minimal, port it directly. If it's a 200-line snippet, cut everything not causally related to the bug.
Tell the user how to run it:
npm run start
open http://localhost:9966/debug/<N>.html
If you can run it yourself (auto mode, MCP browser, etc.), confirm the page loads and the reported failure is visible before declaring done. If you cannot run it, say so explicitly — do not claim the repro works.
End with:
Transform) if obvious, as a starting point for the fix.debug/ so it runs against the local dev build. Sandboxes pin old versions and mask regressions.Always:
debug/<issue-number>.html.npm run start instructions.