Polyfill Cost and Target Browser Policy

Working case

The permit dashboard introduces a new date-formatting feature. One team bundles a large compatibility package into the first screen for every reviewer, even though only the report export path uses the feature. The initial download grows for thousands of users. Another team removes the package entirely because the API appears in current desktop browsers, but a municipal embedded web view cannot render report dates. Both errors come from treating compatibility as a yes-or-no property of a browser rather than a measured task contract.

Implementation boundary

function shouldLoadReportPolyfill(environment) {
  return environment.reportOpened && !environment.hasDateFormatRange;
}
console.log(shouldLoadReportPolyfill({ reportOpened: false, hasDateFormatRange: false }));
// Output: false

List the specific missing feature and the affected workflow. Keep parse compatibility in the build target before a runtime check can execute. Load an API polyfill only where needed, after a cheap feature probe, and verify that it preserves expected behavior rather than merely defining a property. If the missing behavior is small and optional, use a simpler native fallback instead of a full package. Pin and review the dependency as production code. Test bundled and unbundled paths in each supported engine, including the oldest web view still in policy. Document a date to revisit the fallback, but do not remove it on a guess.

Cost and boundaries

A lazy polyfill moves bytes off the initial path, but introduces a later request, parse work, and failure mode. If n users load the app and only a fraction f opens export, initial bytes saved are roughly n times the deferred package size minus export-path fetches; cache behavior changes the real cost. Compatibility branches also increase test combinations. Measure first interaction, export completion, parse time, and support volume. Avoid shipping a polyfill whose dependency cost exceeds the value of the enhanced behavior for the supported audience.

Failure trace

Load the initial dashboard on a supported low-end phone and inspect whether export-only code is absent. Open export and verify the optional package arrives only when needed. Block that package request; the report should use a simpler date representation or an explicit fallback, not a blank screen. Run the build in an engine that cannot parse a newer operator and confirm the configured transform or alternate bundle prevents a startup syntax error. Verify an old embedded web view against the actual report workflow, not only a feature list.

Verification

The build parses in every supported engine.
Optional code stays off the initial path.
A failed polyfill request leaves a usable report.

Practice drill

Define a support matrix for desktop, mobile, and embedded reviewers. Choose one report feature with a missing browser API. Record the before and after initial bundle bytes, optional request bytes, and export completion on three environments. Simulate the polyfill request failing. Keep a short decision record that names the owner, the supported versions, the fallback, and the evidence required before removal.

Decision note

Compatibility is a task-level budget and support contract, not a package that should load on every page.

Common Mistakes

Expecting a runtime polyfill to fix syntax parsing.
Loading export-only code for every visitor.
Assuming a support badge includes embedded web views.

Connected practice

Build Project: progressive case export release and review Web Development: components and compatibility quiz.