tsnapi: snapshot testing for a library's public API surface
Library public API snapshot testing for runtime exports and type declarations.
At a glance
- What is it?
- tsnapi captures runtime exports and type declarations into committed snapshot files, then fails builds when the API changes. It works as a tsdown plugin, a CLI, or a Vitest integration.
- Who is it for?
- Adopt tsnapi if you maintain a TypeScript library and want every public API change to appear in git diffs and block CI until reviewed. Skip it if your package has no stable public contract, or if you cannot commit generated snapshot files.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- antfu/tsnapi206 ★ · +8
| Repository | 2026-08-24 | 2026-11-15 |
|---|---|---|
| antfu/tsnapi | 198 | 206 |
8 Stars in the last 83 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What problem it solves and who should care
Library maintainers routinely break consumers by renaming an export, changing a function signature, or widening a type in a way that callers did not expect. These changes are easy to miss in a pull request because the diff shows code, not the public contract. tsnapi turns that contract into two text files per entry point: a .snapshot.js for runtime exports and a .snapshot.d.ts for type declarations. You commit these files, and any change to the API surface shows up as a normal git diff. The intended audience is anyone publishing a TypeScript package, especially in a monorepo where multiple packages share a build step. The README frames it as Vitest snapshot testing, but for a package's public contract rather than for component output.
How the snapshots are produced and compared
tsnapi reads the built dist files, not the source. It parses the package.json exports field to find each entry point, then extracts what the built files actually expose at runtime and in the type declarations. The output is a pair of human-readable snapshot files per entry. On a normal build, the tool compares the current output against the committed snapshots and fails the build if anything changed, additive or breaking. The comparison is deliberately lossy, as the README states. It favours not blocking a change to avoid false positives, while reliably catching removals. A declaration losing something, like a removed export, interface member, parameter, or union arm, is classified as breaking. A purely additive change, such as a new export or a widened parameter type, is allowed through during an update. The guard only runs while updating, but a normal comparison build still fails on any change, so every change lands in the git diff.
Installation and the tsdown plugin workflow
Install with pnpm add -D tsnapi. The recommended path is the Rolldown or tsdown plugin. In tsdown.config.ts you import ApiSnapshot from 'tsnapi/rolldown' and add it to the plugins array, with dts: true so types are generated. On the first build, snapshot files are written. On subsequent builds, the plugin compares and fails the build with a diff if the API changed. To update snapshots intentionally, you set update: true in the plugin options, or pass the --update-snapshot or -u CLI flag to tsdown, or set UPDATE_SNAPSHOT=1 in the environment. The README gives a concrete example: tsdown --update-snapshot or UPDATE_SNAPSHOT=1 tsdown. The update mode then classifies changes as additive or breaking. A breaking change aborts the update without overwriting the snapshot, so a routine -u cannot silently ship a breaking change.
The breaking change guard and its deliberate gaps
The guard's logic is simple: a change is breaking only when a declaration loses something. The README includes a table showing that removing an export, removing an interface member, parameter, or union arm, and replacing a type with an unrelated one are all breaking. Adding an export, adding an interface property, widening a parameter or return type with a union, and adding a parameter are additive. The guard intentionally lets some genuinely breaking changes through. Widening a return type, which callers may not expect, is classified as additive to keep false positives low. That is a trade-off. The tool catches the most obvious breakage, but not every semantic break. The README is honest about this: a normal comparison build still fails on any change, so the diff is always visible. If you need a stricter guarantee, you would have to rely on the diff review, not on the guard's classification.
CLI usage and the interactive inspector
The CLI works without a bundler. Running tsnapi snapshots the current package by reading package.json exports and parsing the dist files. You must build first to generate the dist. The -u flag updates snapshots, and --allow-breaking permits a breaking change during an update. The environment variable TSNAPI_ALLOW_BREAKING=1 also works. There is also an interactive inspector, tsnapi ui, built on devframe and @antfu/design. It visualizes the public API of every package in a workspace as a graph, with nodes for workspace, package, entry, and member, coloured by kind and diff status. It reads only committed __snapshots__ files, never regenerates them. You can diff two git refs or the working tree, and export a static build with tsnapi ui build --out-dir dist-inspector. The inspector reuses the same breaking-change analysis, so the diff statuses match the guard's classification.
Vitest integration and build ordering
The tsnapi/vitest module provides a higher-level integration that uses Vitest's toMatchFileSnapshot to store snapshots as individual files. You call snapshotApiPerEntry(dir) inside a describe block, and it creates it() blocks for each entry point. The README warns that tsnapi reads built dist files, so you must build before running tests. It recommends changing the test script to pnpm run build && vitest. If you use tsdown, the README points to tsdown-stale-guard to set up a build guard automatically. This ordering constraint is a real operational cost: every test run triggers a full build, which can be slow in large monorepos. The alternative is to run tsnapi as a separate step in CI, not inside the test suite.
Maintenance cost and license implications
The repository is under the MIT license, which permits commercial use, modification, and redistribution with attribution. The project is actively maintained, with releases in July and August 2026, but the README does not document a migration path or upgrade notes. The snapshot files themselves are committed, so every API change requires a deliberate update step. That is the main maintenance cost: you must train contributors to run tsnapi -u when they intentionally change the API, and to review the diff before committing. The allow-breaking flag is a dangerous convenience, because it bypasses the guard entirely. The README shows the exact commands, but does not explain how to audit which changes were allowed through. In practice, you should treat --allow-breaking as a last resort and require a separate review for any update that uses it.
Alternatives and when tsnapi is the wrong tool
The closest alternative is API Extractor, which generates a .api.md report file from TypeScript declarations and can be configured to fail on changes. The difference in approach is that API Extractor works at the declaration level only and does not capture runtime exports. tsnapi covers both runtime and types, and it integrates directly with tsdown, which API Extractor does not. Another alternative is to write hand-rolled tests that assert on the exports object and type assignments, but those are brittle and do not produce a readable diff. tsnapi is the wrong tool if your package has no stable public contract, or if you cannot commit generated files because of policy or repo size. It is also redundant if you already use API Extractor and do not need runtime export snapshots. The lossy breaking guard means tsnapi is not a substitute for a full semver check; it is a visibility tool, not a correctness proof.
Editorial conclusion
Adopt tsnapi if you maintain a TypeScript library and want every public API change to appear in git diffs and block CI until reviewed. Skip it if your package has no stable public contract, or if you cannot commit generated snapshot files. Before adopting, verify that your build pipeline can run tsnapi after dist generation, and decide how you will handle the deliberate allow-breaking escape hatch. The tool's own snapshots are in the repo, so check them to see what the output actually looks like before committing to the workflow.
Frequently asked questions
What does tsnapi do?
It captures your package's public API surface, both runtime exports and type declarations, into human-readable snapshot files you commit alongside your code. Every build produces a .snapshot.js and a .snapshot.d.ts per entry point, and an unexpected change shows up as a diff.
How do I install and run tsnapi?
Add it as a dev dependency with pnpm add -D tsnapi. The recommended integration is a plugin for tsdown, and there is also a standalone CLI, where a bare tsnapi run snapshots the current package by reading the package.json exports and parsing dist files, so you must build first.
What counts as a breaking change in tsnapi?
A change is breaking when a declaration loses something: removing an export, removing an interface member, a parameter or a union arm, or replacing a type with an unrelated one. Additions are additive and pass through, and the guard is deliberately lossy to avoid false positives.
Why does my tsnapi update refuse to overwrite the snapshot?
Because the change was classified as breaking, so the update aborts and leaves the existing snapshot in place. If that is intentional, re-run with the --allow-breaking flag, set TSNAPI_ALLOW_BREAKING=1, or pass allowBreaking in the plugin options.
Does tsnapi catch every breaking change?
No, and the documentation says so. Because the guard only checks that nothing was removed, some genuinely breaking changes, such as widening a return type that callers may not expect, are intentionally allowed through to keep false positives low. A normal comparison build still fails on any change.
What does the tsnapi inspector do and what does it not do?
It visualises the public API of every package in a workspace as an interactive graph, from workspace down to package, entry and member, and can diff two git refs. It only reads already generated snapshot files and never regenerates them, so run tsnapi or tsnapi -u first.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/antfu-tsnapi)Star history chart for your README
[](https://hysenlabs.com/projects/antfu-tsnapi)Was this useful?