Start from something that fails every time#
Reduce from a reproduction that fails reliably: a script, or exact steps against a page. If it fails only sometimes, make it deterministic first, for example by holding one response or fixing the clock. Reducing a flaky reproduction loses the bug without telling you why.
Remove in halves#
- Copy the failing page or component into a new, empty project with only the libraries it imports.
- Remove half of what remains: half the components, half the CSS, half the data.
- Check that it still fails.
- It still fails: keep the removal.
- It stops failing: put that half back and remove the other half instead.
- Repeat until removing anything stops the failure.
Replace what you cannot remove with something simpler: a fetch with a hard-coded JSON response, a component with the plain HTML it renders, a store with a constant.
What the finished reproduction holds#
- A short README: the steps, the expected result and the actual result
- Exact versions of every dependency, with a lockfile
- Nothing private: no API keys, no customer data, no internal URLs
- The fewest files that show the bug, often one component or one HTML file
Choose where to put it#
| Form | Fits |
|---|---|
| A single HTML file | Browser behavior with no build step. Serve it over http://localhost rather than opening it from disk; origin differences explains why. |
| A public repository | Anything with a build step or several files; the maintainer clones and runs it |
| An online sandbox from a framework's template, such as StackBlitz or CodeSandbox | Framework bugs; many projects' issue templates link one. Check the sandbox's runtime matches yours, since some run Node in the browser. |
| A failing test in the project's own test suite | Bugs in a library you can clone, and the most useful form for its maintainers |
Many projects say in their issue template what they accept. Read it first, because some close issues without a reproduction link.
What the reduction tells you#
Each step that stops the failure points at a cause. If removing a CSS file stops it, the bug is in styles. If replacing the API call with a constant stops it, the bug depends on the response's timing or shape. Write the last removal that stopped the failure in the report: "fails with ThemeProvider, passes without it" is a strong lead.
Sometimes the reduction ends with the bug in your own code. That is a good outcome: you found it without waiting for a maintainer.
Worked example: a library bug that was a configuration#
This example is fictional. A team reports to a date-picker library's maintainers that the picker shows English month names in a German app. The maintainers ask for a minimal reproduction.
Copying the picker into an empty Vite project with locale="de" shows German names. Adding the app's pieces back in halves, the English names return when the app's bundler configuration is added: it excluded the library's locale files to shrink the bundle. The picker fell back to English silently. The team withdrew the bug report and opened a feature request instead, asking the library to warn when a requested locale is missing. The maintainers accepted it the same day.
Questions#
How small is small enough?
Small enough that someone unfamiliar with your app can read it in a few minutes. A few dozen lines is common; a whole route of your app is not.
What if the bug needs our backend?
Record the responses the page needs and serve them from static files or a mock in the reproduction. Replay recorded responses shows one way. Remove personal data from them first.
Should the reproduction include a fix?
If you have one, link it separately. The reproduction should show the bug on the unmodified version.
Return to reproducing what someone else saw for the other layers a replay needs.