Skip to content

feat: publish a browser global build loadable with a classic script tag - #441

Merged
kevinccbsg merged 2 commits into
mainfrom
feat/global-iife-build
Nov 18, 2026
Merged

kevinccbsg merged 2 commits into
mainfrom
feat/global-iife-build

Conversation

@kevinccbsg

@kevinccbsg kevinccbsg commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Closes #440

What

Adds dist/twd.global.js, an IIFE build that exposes window.TWD. One classic <script src> gives you what three ESM imports give you today:

  • initTWD (from twd-js/bundled)
  • twd, userEvent, screenDom, screenDomGlobal, expect (from twd-js)
  • describe, it, beforeEach, afterEach (from twd-js/runner)

It is meant for environments that run classic scripts but block import maps and module scripts, such as Slack's mobile preview of attached HTML prototypes.

<script src="https://cdn.jsdelivr.net/npm/twd-js@1.13.0/dist/twd.global.js"></script>
<script>
  const { initTWD, describe, it, screenDom, expect } = window.TWD;
  initTWD({ scenarios: async () => { /* describe / it */ } }, { serviceWorker: false });
</script>

How

  • src/browser-global.ts: new entry that only re-exports existing modules. Everything sits in one module graph, so the runner and the sidebar share the same state.
  • vite.global.config.ts: separate config (formats: ["iife"], name: "TWD", Preact preset, no dts plugin). It runs as an extra step in npm run build.
  • process.env.NODE_ENV is defined at build time. Lib mode leaves it for the consumer's bundler, but an IIFE has none, and react-is (via @testing-library/dom) reads it unguarded, which threw process is not defined in the browser.
  • unpkg / jsdelivr fields in package.json point at the new file, so the bare CDN URL works.
  • Docs: new "Classic script tag" subsection under Vanilla JS in docs/frameworks.md.

Request mocking is out of scope for this build: it needs mock-sw.js on the page's origin, which these environments can't provide. The docs say to use serviceWorker: false.

Impact on existing outputs

None. I hashed every file in dist/ before and after: all 27 existing files are byte-identical, and the only difference is the new twd.global.js. exports is unchanged.

Size: 381 KB, 96.7 KB gzipped (the esbuild prototype in the issue was 558 KB / 135 KB, because it resolved to React instead of Preact).

Testing

  • src/tests/global/browser-global.spec.ts checks that the entry exposes the full API. It was written first and failed before the entry existed.
  • Manual smoke test: loaded the built file into jsdom as a classic script (no module scripts on the page), checked that all 10 keys are on window.TWD, that the sidebar renders the test, and that Run All runs it and it passes. This is the check that caught the process issue.
  • Full suite: 547 tests pass.

Release

Needs a minor release (1.13.0) for the CDN URL to exist. The docs example already uses that version.

Add dist/twd.global.js, an IIFE build that exposes window.TWD with
initTWD, the test API and the runner in one file, for environments that
block import maps and module scripts. Built from a separate config so the
existing ESM and bundled outputs are unchanged.

Closes #440
With src/global.ts next to src/global.d.ts, TypeScript treated the .d.ts as
the declaration file of the .ts and dropped the window augmentations, which
broke lint (no-unsafe-assignment in pace.ts) and the dts build.
@kevinccbsg
kevinccbsg merged commit d6eb60b into main Nov 18, 2026
10 checks passed
@kevinccbsg
kevinccbsg deleted the feat/global-iife-build branch November 18, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Publish a browser global build (IIFE) loadable with a classic script tag

1 participant