Polyfilling Array.prototype.flatMap with core-js: A Step‑by‑Step Guide for Legacy Browser Support

Desired Outcome

Ensure that Array.prototype.flatMap is available and behaves according to the ES2019 specification in all target browsers, including IE11 and older Chrome/Edge versions, without overriding native implementations or introducing unnecessary overhead.

Prerequisites

• Node.js environment with npm or yarn for package installation.
• Project using a module bundler (Webpack, Rollup, Vite, etc.) or a build system that can import ES modules.
• core-js version 3.x or newer (the polyfill is not available in core-js 2).
• Target browsers that lack native flatMap support (e.g., IE11, Chrome 49).

Procedure

1. Install core-js

   npm install core-js@3 --save

2. Import the polyfill in your entry point

   Place this import before any code that uses flatMap:

   import 'core-js/es/array/flat-map';
   // If you also need Array.prototype.flat, import that first:
   import 'core-js/es/array/flat';
   // Now you can safely call flatMap anywhere in the bundle.

   core-js checks for native support internally and will only add the method if it is missing.

3. Verify the polyfill at runtime

   if (!Array.prototype.flatMap) {
     console.warn('flatMap polyfill failed to load');
   } else {
     console.log('flatMap is available');
   }
   // Basic functional test
   console.log([1, 2, 3].flatMap(x => [x, x])); // Expected: [1,1,2,2,3,3]

4. Bundle configuration
   • In Webpack, ensure core-js is not duplicated by using externals or a shared node_modules folder.
   • In Rollup, add node-resolve and commonjs plugins to handle core-js imports.
5. Optional: Specify a browserlist configuration

   {
     "browserslist": [
       "last 2 Chrome versions",
       "last 2 Firefox versions",
       "IE 11"
     ]
   }

   Modern bundlers can use this to automatically include the necessary polyfills.

Runtime Checks

After bundling, run the following checks in the target environment:

• Confirm the method exists: typeof Array.prototype.flatMap === 'function'.
• Ensure it is not the native implementation (rare but possible in older browsers):

  console.log(Object.prototype.toString.call(Array.prototype.flatMap));
  // Should not return "[object NativeFunction]" in environments where native support is missing.

• Test behavior with sparse arrays:

  console.log([1,,3].flatMap(x => [x, x])); // Expected: [1,1,3,3]

Recovery Options

• If the polyfill is missing after deployment, fallback to a manual implementation:

  function safeFlatMap(arr, fn, thisArg) {
    return arr.reduce((acc, val, idx) => {
      const mapped = fn.call(thisArg, val, idx, arr);
      return acc.concat(mapped === null || mapped === undefined ? [] : mapped);
    }, []);
  }

• Use a runtime loader (e.g., import()) to dynamically load core-js/es/array/flat-map if Array.prototype.flatMap is undefined.

Performance Considerations

The core-js polyfill introduces a modest overhead due to its generic implementation. For performance‑critical code paths, consider:

• Using Array.prototype.reduce with manual concatenation as shown above.
• Conditionally applying the polyfill only in production builds that target legacy browsers.
• Profiling the bundle size impact: the es/array/flat-map module is ~2KB gzipped.

Bundle Size Tips

To keep the bundle lean:

• Import only the modules you need (avoid importing core-js/stable).
• Use tree‑shaking enabled bundlers; core-js exports are side‑effect free after the import.
• Check for duplicate imports across multiple entry points; consolidate them.

Wrap‑Up

By importing core-js/es/array/flat-map early in your bundle you guarantee consistent flatMap behavior across all browsers your application supports. The polyfill respects native implementations, so it won’t overwrite them. Follow the runtime checks to confirm integration, and be mindful of the small performance cost in heavy‑use scenarios.