Browser compatibility is a release decision, not a guess. This guide gives you a reusable checklist for evaluating JavaScript language features and Web APIs, choosing between detection, polyfills, and fallbacks, and testing the result against the browsers your project actually supports.
Overview
JavaScript browser compatibility has two separate dimensions: whether a browser can parse and execute a language feature, and whether it implements a particular Web API. A browser may understand modern syntax but lack an API, or it may expose an API with incomplete behavior. Treating these as the same problem is a common source of production bugs.
Start by defining a support policy for the application. List the browsers, browser versions, operating systems, embedded webviews, and device classes that matter to your users. Your answer may differ for a public marketing site, an internal business application, and a consumer product with a large mobile audience. Do not use a vague goal such as “support modern browsers” without translating it into testable targets.
Then classify the feature you want to use:
- JavaScript syntax: examples include optional chaining, nullish coalescing, classes, modules, and newer operators. Unsupported syntax can prevent an entire script from parsing.
- Built-in language features: examples include newer methods on arrays, objects, strings, promises, or other built-in objects. Syntax transformation does not always provide these methods.
- Web APIs: examples include browser capabilities for storage, networking, media, workers, notifications, and device interaction. These require API-specific checks.
- Behavior and implementation details: an API can exist while differing in edge-case behavior, permissions, limits, or performance.
Use a compatibility reference or your project’s browser-support tooling to check the exact feature, not a nearby feature with a similar name. Record the result in a small decision note: target browsers, required behavior, detection method, fallback, and test evidence. This makes compatibility part of the design rather than a last-minute debugging task.
Checklist by scenario
When adding JavaScript syntax
- Confirm that your build tool parses the syntax.
- Check whether the build output is transformed for every target browser.
- Verify that the output format itself is supported, especially when shipping modules or modern bundles.
- Test the built files, not only the source files, in representative browsers.
A transpiler can rewrite syntax, but it cannot automatically provide every missing runtime feature. For example, transforming a newer syntax form does not necessarily add a missing built-in method. Review the generated bundle and identify whether a runtime helper or polyfill is also needed.
When using a built-in method
- Check the method’s support independently from the syntax used to call it.
- Decide whether a polyfill is appropriate for the application’s targets.
- Prefer a focused polyfill or a build-time strategy when only a small compatibility gap exists.
- Test unusual inputs, such as empty collections, inherited properties, large values, and rejected promises.
Be precise about what must be preserved. A replacement that merely prevents an error may still differ in ordering, coercion, exceptions, or asynchronous behavior. Read the method’s expected semantics before selecting a fallback.
When using a Web API
- Check whether the API exists in the relevant global object.
- Check whether the operation is allowed in the current context, such as a secure context, worker, iframe, or permission state.
- Handle rejected promises and runtime exceptions even after a positive feature check.
- Provide a useful alternative if the capability is unavailable or denied.
Use capability detection rather than browser or operating-system detection:
if ('serviceWorker' in navigator) {
// Register or use the capability.
} else {
// Keep the core experience available without it.
}For a method that may be absent, test the method itself:
if (typeof window.SomeAPI?.performAction === 'function') {
window.SomeAPI.performAction();
} else {
showStandardAction();
}The optional chaining in this example must itself be safe for the browsers that parse the script. If it is not, let your build process transform it or use syntax that your target environment accepts.
When a feature improves the experience but is not essential
Use progressive enhancement. Render the primary content and action first, then add the enhanced behavior when the capability is available. A map can fall back to an address and link; drag-and-drop can fall back to a file picker; client-side filtering can fall back to a server request. This approach reduces the number of compatibility decisions that can block the main task.
When a dependency introduces the feature
Inspect the package’s supported environments, build output, and runtime assumptions before adding it. Check whether it ships multiple builds, requires a global polyfill, depends on a browser-only object, or assumes a particular module format. The guide How to Evaluate npm Packages Before Adding Them to a JavaScript Project provides a useful companion checklist. Also include compatibility in code review and automated tests, as described in the JavaScript Code Review Checklist.
What to double-check
Feature detection is not a complete test
A property may be present while the feature is unusable in a particular context. Permissions, user settings, network conditions, document policy, iframe restrictions, and unavailable hardware can all affect the result. Treat detection as the first branch in a defensive flow, then handle failure at the point of use.
Polyfill scope and loading
Ask whether the polyfill is global or modular, loaded before dependent code, included in every relevant entry point, and compatible with your module and bundling setup. Confirm that it does not change application behavior in browsers that already provide the native feature. Review bundle size and startup cost as well; compatibility code is still production code.
Server and client assumptions
Code that runs during server-side rendering, static generation, tests, or build steps may not have access to window, document, navigator, or other browser globals. Guard browser-only logic and place it in the appropriate lifecycle or client-side boundary. A feature can be supported by the browser and still fail because it was invoked in the wrong execution environment.
Syntax in all shipped assets
Check application bundles, third-party chunks, worker files, dynamically imported modules, and inline scripts. A compatible main bundle does not help if a lazy-loaded chunk contains unsupported syntax. Your build configuration should apply the intended target policy consistently across these outputs.
Interaction with accessibility and performance
A fallback must remain usable with a keyboard, assistive technology, slow connections, and reduced device capability. Test focus behavior, status messages, and nonvisual alternatives alongside the feature. For a broader process, see the JavaScript Accessibility Testing Workflow and the Frontend Performance Checklist.
Common mistakes
- Checking the browser name: browser detection becomes stale and does not describe the capability in the current context. Test the capability instead.
- Assuming transpilation solves everything: syntax conversion cannot supply every missing API or correct every behavioral difference.
- Using a feature check as a guarantee: an available API can still reject, throw, require permission, or fail because of policy or device conditions.
- Testing only the newest browser: include the least capable supported target and at least one realistic device or webview when relevant.
- Making the fallback an afterthought: a hidden button, empty panel, or confusing error is not graceful degradation. Design the alternate path before implementation.
- Over-polyfilling: loading a large compatibility bundle for every visitor can increase startup work. Use targeted or differential strategies when they fit the project.
- Ignoring generated code: source-level review can miss unsupported syntax emitted by a dependency or separate build entry.
For an end-to-end verification plan, combine compatibility checks with unit, integration, and browser tests. The JavaScript Testing Guide can help separate these layers, while the Modern JavaScript Project Setup guide covers the tooling that keeps target settings consistent.
When to revisit
Review browser compatibility before introducing a new API, changing your browser-support policy, upgrading a framework or dependency, modifying the build pipeline, or removing a fallback. Recheck it when a bug report points to one browser family, when a webview or embedded environment is added, and before a significant production release.
A practical recurring workflow is:
- Refresh the project’s supported-browser list and compatibility reference.
- Search the codebase for newly added APIs, syntax, polyfills, and browser-global references.
- Run the build and inspect all browser-facing outputs, including workers and lazy chunks.
- Execute automated tests, then manually verify the essential path in the oldest or least capable supported environment.
- Test the fallback, denied-permission path, network failure path, and accessibility behavior.
- Record the decision and remove obsolete compatibility code only when the support policy and usage evidence justify it.
Keep this checklist with your release or code-review workflow. Compatibility data changes, but the method remains stable: define targets, detect capabilities, transform or polyfill deliberately, preserve a usable fallback, and test the built experience.