Using Array.prototype.flat() Polyfill with Core-js: A Targeted Guide

Quick Answer: Import Only What You Need

Use import 'core-js/es/array/flat' to polyfill Array.prototype.flat() without bloating your bundle. This adds support for flattening nested arrays to a specified depth, with depth 1 as default.

How the Polyfill Works

Core-js provides feature detection: if the target environment has native Array.prototype.flat(), the polyfill is skipped. When needed, it implements the ECMAScript specification's flattening algorithm.

Basic Configuration

In your JavaScript entry point:

// ES module syntax
import 'core-js/es/array/flat';

// CommonJS syntax
require('core-js/es/array/flat');

// Usage after polyfill
const nested = [1, [2, [3, [4]]]];
const flattened = nested.flat(2);
console.log(flattened); // [1, 2, 3, [4]]

Bundler Integration

With webpack or Rollup, tree-shaking removes unused code:

// package.json should include
{
  "dependencies": {
    "core-js": "^3.36.0"
  }
}

// In webpack.config.js, ensure production mode for tree-shaking
module.exports = { mode: 'production' };

Common Mistakes and Pitfalls

Using Full Bundle Instead of Specific Feature

Avoid this:

import 'core-js'; // Adds entire polyfill library

This increases bundle size by ~50-100KB. Always use the specific path core-js/es/array/flat.

Incorrect Depth Handling

The polyfill correctly implements depth behavior:

const data = [1, [2, [3, [4, [5]]]]];

console.log(data.flat());     // [1, 2, [3, [4, [5]]]] - depth 1
console.log(data.flat(1));    // [1, 2, [3, [4, [5]]]] - explicit depth 1
console.log(data.flat(2));    // [1, 2, 3, [4, [5]]] - depth 2
console.log(data.flat(Infinity)); // [1, 2, 3, 4, 5] - all levels

Edge Cases with Sparse Arrays

Sparse array behavior differs between polyfill and native:

const sparse = [1, , 3]; // Hole at index 1
console.log(sparse.flat()); // [1, empty slot, 3] in native
// Polyfill may handle holes differently in some environments

Limitations to Consider

Non-Array Iterables

The polyfill follows ES2019 spec where non-array elements are not recursively flattened:

const mixed = [1, 'hello', [2, 'world']];
console.log(mixed.flat()); // [1, 'hello', 2, 'world']

Performance with Deep Recursion

Using Infinity depth on deeply nested structures can cause stack overflow:

const deep = Array(1000).fill(null).map(() => [1]);
// deep.flat(Infinity) may exceed call stack

Version Compatibility

Core-js 3.x supports ES2019 flat(). Older core-js 2.x requires different import paths and may not fully implement the spec.

Verification Steps

Check Native Support

Verify polyfill only loads when needed:

if (typeof Array.prototype.flat !== 'function') {
  console.log('Polyfill required');
  // Load core-js/es/array/flat
}

Verify Bundle Output

After bundling, check that:

• Modern browsers (Chrome 66+, Firefox 62+, Safari 12+) skip the polyfill
• Bundled code doesn't include full core-js library
• Only es/array/flat functionality is present

Test Flattening Behavior

Run in target environments:

const testCases = [
  [[1, 2], [3, 4]],
  [1, [2, [3, [4]]]],
  [],
  [[], [[]], [[[]]]]
];

testCases.forEach(arr => console.log(arr.flat(2)));

Environment Support Matrix

Environment	Version	Native Support
Chrome	66+	Yes
Firefox	62+	Yes
Safari	12+	Yes
Node.js	11+	Yes
IE 11	-	No (requires polyfill)

Key Takeaway

Import core-js/es/array/flat specifically rather than the full core-js bundle. This provides Array.prototype.flat() support with minimal bundle impact, while core-js's built-in feature detection prevents unnecessary polyfill loading in modern environments.