+{"description":"\n# Comparing Transpiled Output\n\nWhen migrating build tooling — Babel → SWC, `tsc` → `tsgo`, a Babel preset\nbump, a TypeScript upgrade — you want to know whether the change actually\naltered the emitted code. `transpile-diff` builds two git refs in isolation\nand diffs their `es/`, `lib/` and `types/` output.\n\n```bash\npnpm run transpile-diff [refA] [refB]\n```\n\n- `refA` defaults to `master`, `refB` to the current branch (`HEAD`).\n- **Any git ref works** — a branch, a tag (`v9.0.0`), or a commit SHA.\n\n```bash\npnpm run transpile-diff # current branch vs master\npnpm run transpile-diff master my-swc-branch # two branches\npnpm run transpile-diff v9.0.0 HEAD # a release vs now\n```\n\n## How it works\n\nFor each ref the command:\n\n1. checks it out into a temporary git worktree under `.transpile-diff/`,\n2. runs `pnpm install --frozen-lockfile` then `pnpm run bootstrap` (a clean,\n full build — so `types/` declarations are included),\n3. snapshots the built output, passing each file through a normalization step\n that strips the license banner, sourcemap comments and whitespace noise.\n\nIt then diffs the two snapshots, prints a `changed / added / removed` summary,\nwrites an HTML report to `.transpile-diff/report-<a>-<b>.html` (opened\nautomatically), and exits non-zero if anything differs.\n\nSnapshots are cached by commit SHA, so re-running against an unchanged ref\n(e.g. `master`) skips its rebuild.\n\n## Options\n\n| Option | Default | Description |\n| ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--modules` | `es,lib,types` | Which output dirs to compare. |\n| `--semantic` | `false` | Reprint each file with the repo's `dprint` config before diffing, so pure-formatting differences are ignored. **Recommended for Babel→SWC / tsc→tsgo**, where output is never byte-identical but should be semantically equivalent. |\n| `--raw` | `false` | Skip normalization entirely — compare raw bytes (banner, whitespace included). |\n| `--no-frozen` | _(off)_ | Allow lockfile changes when installing. Useful for old refs whose lockfile no longer resolves under the current toolchain. |\n| `--no-open` | _(off)_ | Don't open the HTML report automatically. |\n\n### Which mode to use\n\n- **Same compiler, config bump** (e.g. a TypeScript version upgrade): the default normalization is enough — output formatting is stable, so any diff is a real change.\n- **Different compiler** (Babel→SWC, tsc→tsgo): add `--semantic`. Babel and SWC will never produce byte-identical output, but after reprinting through `dprint` the diff reduces to genuine code differences.\n\n`--semantic` uses `dprint`, which is already a ui-scripts dependency — it adds no new packages.\n\n## Notes\n\n- A full `bootstrap` runs per ref, so a cold run takes several minutes — this\n is meant to be run occasionally, not in CI.\n- Comparing very old commits can fail at the **build** step (lockfile or Node\n version drift), not the diff step. The command aborts with a clear message\n identifying which ref failed to build rather than reporting a misleading diff.\n","title":"Comparing Transpiled Output","category":"Contributing","order":8,"relativePath":"docs/contributing/transpile-diff.md","extension":".md","srcPath":"docs/contributing/transpile-diff.md","srcUrl":"https://github.com/instructure/instructure-ui/tree/master/docs/contributing/transpile-diff.md","packageName":"@instructure/docs","requirePath":"@instructure/docs/contributing/transpile-diff","requireStr":"require('/home/runner/work/instructure-ui/instructure-ui/docs/contributing/transpile-diff.md').default","esPath":"@instructure/docs/contributing/transpile-diff","themePath":"docs/contributing/transpile-diff.md","themeUrl":"https://github.com/instructure/instructure-ui/tree/master/docs/contributing/transpile-diff.md","id":"transpile-diff"}
0 commit comments