core-js - Documentation

What is Core-JS?

Core-JS is a JavaScript library that provides polyfills for ECMAScript features that are not yet implemented or implemented inconsistently across different browsers. It aims to provide a consistent and reliable way to use modern JavaScript features in older browsers without relying on transpilers like Babel. Core-JS focuses on providing only the polyfills themselves, leaving the actual usage and integration up to the developer. This modular approach allows for only including the necessary polyfills, minimizing the overall bundle size.

Why use Core-JS?

Using Core-JS offers several advantages:

• Cross-browser compatibility: Write modern JavaScript code and have it run reliably on a wide range of browsers, including older ones that lack support for newer features.
• Reduced bundle size: Its modular design allows you to include only the specific polyfills needed for your project, avoiding unnecessary code bloat. This improves performance and load times.
• Maintainability: As new ECMAScript features are standardized, Core-JS is updated to provide corresponding polyfills. This simplifies the process of keeping your code up-to-date with the latest standards.
• No transpilation: Unlike transpilers, Core-JS directly polyfills the features at runtime, making your development workflow simpler and avoiding the complexities of transpilation.
• Community-driven and well-maintained: Core-JS is a mature and actively maintained project with a strong community behind it, ensuring ongoing support and updates.

Core-JS vs. Polyfills

While Core-JS is a collection of polyfills, it’s crucial to understand the distinction. A polyfill is a piece of code that provides functionality missing in a specific environment. Core-JS is a comprehensive library that provides a large collection of these polyfills, organized and maintained as a single unit. You could create your own individual polyfills, but Core-JS offers a ready-made, tested, and well-maintained solution. Using individual polyfills from various sources can lead to conflicts or inconsistencies.

Installation and Setup

Core-JS can be installed using npm or yarn:

npm install core-js
# or
yarn add core-js

Using Core-JS 3 (recommended): Core-JS 3 uses a modular approach. You should import only the specific modules you need. This is generally done using the import syntax. For example, to use the Promise polyfill:

import 'core-js/modules/es.promise';

// Now you can use Promises reliably, even in older browsers.

To include multiple modules, import them individually:

import 'core-js/modules/es.array.includes';
import 'core-js/modules/es.object.assign';

A more convenient way to import modules, especially if you need many, is using core-js/stable which provides all commonly used stable polyfills. For production, this is a simpler option that has smaller overhead compared to importing each module individually.

import 'core-js/stable';

Using Core-JS 2 (deprecated, but some projects still rely on it): Core-JS 2 uses a different approach, often including the entire library. While it might seem simpler initially, it leads to larger bundles. Its usage is discouraged in favor of Core-JS 3’s modularity.

require('core-js/fn/array/includes'); // Example using require for Core-JS 2

Browsers Compatibility

Core-JS aims for broad compatibility. However, it’s important to note that some very old or obscure browsers may still have limitations. While Core-JS helps bridge these gaps, it’s not a silver bullet for every browser compatibility issue. Refer to the official Core-JS documentation and release notes for the most up-to-date information on supported browsers and any known limitations for specific polyfills. Testing on your target browsers is essential. Generally speaking, Core-JS provides good compatibility with modern browsers and most widely used older ones.

Working with Core-JS

Import Statements

Core-JS 3 uses ES modules, so you import polyfills using standard JavaScript import statements. This allows for optimal tree-shaking and reduces the final bundle size significantly. Avoid using require() which is associated with older CommonJS modules and not ideal for modern builds.

Using Individual Modules

The recommended approach is to import only the specific polyfills your application requires. This granular control minimizes the amount of code included in your final bundle, leading to faster load times and a smaller application footprint. Each polyfill is organized within the core-js/modules directory, categorized by ECMAScript specification and feature.

For example, to add support for Array.prototype.includes():

import 'core-js/modules/es.array.includes';

const array = [1, 2, 3];
console.log(array.includes(2)); // true

To include multiple modules, simply list them in separate import statements:

import 'core-js/modules/es.promise';
import 'core-js/modules/es.array.flat';
import 'core-js/modules/es.object.from-entries';

This approach ensures that only the necessary polyfills are included in your build.

Using the Bundled Version (core-js/stable)

For convenience, Core-JS provides a bundled version (core-js/stable) containing a selection of commonly used polyfills. This is useful for rapid prototyping or when you need a broader set of features and don’t want to meticulously select individual modules. However, it will lead to a larger bundle size than importing individual modules.

import 'core-js/stable';

Remember that this imports a significant number of polyfills; it’s less efficient than the modular approach for production applications where bundle size is crucial. Use it judiciously. core-js/stable is suitable for development or smaller projects where the added bundle size isn’t a significant concern.

Tree-shaking and Optimization

Modern bundlers (like Webpack, Rollup, Parcel, etc.) effectively support tree-shaking with Core-JS 3’s modular approach. This means that unused imported modules are automatically eliminated during the build process, resulting in a smaller final bundle size. To ensure tree-shaking works correctly, make sure your bundler is configured to support ES modules and tree-shaking.

Using individual modules is key to maximizing tree-shaking benefits. Importing core-js/stable will likely prevent efficient tree-shaking since the entire bundle is imported.

Versioning and Updates

Core-JS follows semantic versioning (SemVer). Staying up-to-date is important for security patches and access to new polyfills for emerging JavaScript features. Check the official Core-JS repository for release notes and upgrade instructions. Regularly update your package.json and run npm install or yarn install to obtain the latest version. Consider using a version manager like nvm or similar to ensure you’re using a compatible Node.js version. Always test thoroughly after upgrading to a new version of Core-JS.

Core-JS Modules by Category

This section provides a categorized overview of the polyfills available in Core-JS. Remember to always consult the official Core-JS documentation for the most accurate and up-to-date information on available modules and their specific usage. The import paths shown below assume you are using Core-JS 3’s modular import system.

Array Methods

Core-JS provides polyfills for numerous array methods, including those introduced in recent ECMAScript specifications. Examples include:

• es.array.includes: The includes() method determines whether an array includes a certain value among its entries. import 'core-js/modules/es.array.includes';
• es.array.flat: The flat() method creates a new array with all sub-array elements concatenated into it recursively up to the specified depth. import 'core-js/modules/es.array.flat';
• es.array.flatMap: The flatMap() method first maps each element using a mapping function, then flattens the result into a new array. import 'core-js/modules/es.array.flat-map';
• es.array.from: Creates an array from an iterable object or array-like object. import 'core-js/modules/es.array.from';
• es.array.sort: (Enhanced) The sort() method sorts the elements of an array in place and returns the sorted array. import 'core-js/modules/es.array.sort';
• Many more: Consult the Core-JS documentation for a complete list.

Object Methods

Polyfills for manipulating objects:

• es.object.assign: Copies the values of all enumerable own properties from one or more source objects to a target object. import 'core-js/modules/es.object.assign';
• es.object.entries: Returns an array of a given object’s own enumerable string-keyed property [key, value] pairs. import 'core-js/modules/es.object.entries';
• es.object.from-entries: Transforms a list of key-value pairs into an object. import 'core-js/modules/es.object.from-entries';
• es.object.get-own-property-descriptor: Returns a property descriptor for an own property (that is, one directly present on the object, not inherited) of a given object. import 'core-js/modules/es.object.get-own-property-descriptor';
• es.object.get-own-property-names: Returns an array of a given object’s own enumerable property names, iterated in the same order that a for…in loop would enumerate them. import 'core-js/modules/es.object.get-own-property-names';
• Many more: Including methods for defining getters and setters, freezing objects, and more.

String Methods

Polyfills for string manipulation:

• es.string.includes: Determines whether one string may be found within another string. import 'core-js/modules/es.string.includes';
• es.string.starts-with: Determines whether a string begins with the characters of another string, returning true or false as appropriate. import 'core-js/modules/es.string.starts-with';
• es.string.ends-with: Determines whether a string ends with the characters of another string, returning true or false as appropriate. import 'core-js/modules/es.string.ends-with';
• es.string.trim: Removes whitespace from both ends of a string. import 'core-js/modules/es.string.trim';
• es.string.trim-start: Removes whitespace from the beginning of a string. import 'core-js/modules/es.string.trim-start';
• es.string.trim-end: Removes whitespace from the end of a string. import 'core-js/modules/es.string.trim-end';
• es.string.pad-start: Pads the current string with another string (multiple times, if needed) until the resulting string reaches a given length. The padding is applied from the start (left) of the current string. import 'core-js/modules/es.string.pad-start';
• es.string.pad-end: Pads the current string with another string (multiple times, if needed) until the resulting string reaches a given length. The padding is applied from the end (right) of the current string. import 'core-js/modules/es.string.pad-end';
• And many more: Including methods for repeat, code point at, etc.

Number Methods

Polyfills related to number objects:

• es.number.is-finite: Determines whether a value is a finite number. import 'core-js/modules/es.number.is-finite';
• es.number.is-integer: Determines whether a value is an integer. import 'core-js/modules/es.number.is-integer';
• es.number.is-nan: Determines whether a value is NaN (Not a Number). import 'core-js/modules/es.number.is-nan';
• es.number.is-safe-integer: Determines whether a numeric value is a safe integer. import 'core-js/modules/es.number.is-safe-integer';
• es.number.parse-float: Parses a string argument and returns a floating point number. import 'core-js/modules/es.number.parse-float';
• es.number.to-fixed: Returns a string representing the number to fixed decimal places. import 'core-js/modules/es.number.to-fixed';

Date Methods

Polyfills for working with dates:

• es.date.to-iso-string: Returns a string representing the date in ISO 8601 format. import 'core-js/modules/es.date.to-iso-string';
• es.date.to-json: Returns a string representing the date in ISO 8601 format. import 'core-js/modules/es.date.to-json';
• es.date.to-string: Returns a string representing the date. import 'core-js/modules/es.date.to-string';

Symbol Methods

Polyfills for the Symbol type:

• es.symbol: Provides polyfills for Symbol constructor and related methods. import 'core-js/modules/es.symbol';

Map, Set, WeakMap, WeakSet

Polyfills for collection types:

• es.map: Polyfill for the Map object. import 'core-js/modules/es.map';
• es.set: Polyfill for the Set object. import 'core-js/modules/es.set';
• es.weak-map: Polyfill for the WeakMap object. import 'core-js/modules/es.weak-map';
• es.weak-set: Polyfill for the WeakSet object. import 'core-js/modules/es.weak-set';

Promise Methods

Polyfills for promises:

• es.promise: Provides the Promise object and its methods. import 'core-js/modules/es.promise';

Reflect API

Polyfills for the Reflect object:

• es.reflect: Polyfills for Reflect API methods. import 'core-js/modules/es.reflect'; (Often includes multiple submodules)

Global Methods

Polyfills for global methods:

• es.global-this: Provides the globalThis global object. import 'core-js/modules/es.global-this';

Intl (Internationalization)

Polyfills for internationalization:

• Various modules under es.intl: These modules provide polyfills for different aspects of the Intl API (e.g., es.intl.locale, es.intl.numberformat, es.intl.datetimeformat). Consult Core-JS documentation for specifics.

Typed Arrays

Polyfills for typed arrays:

• Modules under es.typed-array: Provides various typed array polyfills (e.g., Int8Array, Uint8Array, etc.).

Other Utility Methods

Core-JS includes several other utility polyfills that don’t neatly fit into the above categories. Consult the Core-JS documentation for a complete list. Examples may include polyfills for features related to iterators, generators, and more. Always check the official documentation for the most current listing and details.

Advanced Usage and Configuration

Customizing the Build Process

While Core-JS 3’s modularity simplifies the import process, you might need to customize your build process for complex scenarios. This typically involves configuration within your bundler (Webpack, Rollup, Parcel, etc.).

• Webpack: Webpack’s configuration allows fine-grained control over how Core-JS modules are handled. You can adjust the resolve and module sections to optimize imports and tree-shaking. Experiment with different loaders and plugins to improve your build process.

• Rollup: Rollup provides similar customization options. You can adjust plugin configurations to ensure correct handling of ES modules and tree-shaking. Pay particular attention to plugins that handle ES modules and dead code elimination.

• Parcel: Parcel generally handles ES module imports seamlessly. However, for very large projects or specific optimization needs, you may need to explore its configuration options.

In all cases, ensure your bundler is configured to correctly handle ES modules and perform tree-shaking. Incorrect configurations can lead to larger-than-necessary bundle sizes or runtime errors. Consult your bundler’s documentation for detailed instructions.

Debugging and Troubleshooting

Debugging issues related to Core-JS often involves checking for:

• Incorrect Imports: Verify that you’ve imported the correct modules using the appropriate paths. Typos in import statements are a common source of errors.

• Bundler Configuration: Ensure your bundler is correctly configured to handle ES modules and perform tree-shaking. Incorrect configurations can lead to polyfills not being included or unexpected behavior.

• Browser Compatibility: While Core-JS aims for broad compatibility, extremely outdated browsers may still have limitations. Test your application thoroughly on your target browsers.

• Conflicts with Other Libraries: Rarely, conflicts can arise between Core-JS and other libraries. Try isolating the problem by temporarily removing other libraries to see if the issue persists. Check for version compatibility between Core-JS and other dependencies.

• Console Errors: Carefully examine any console errors that appear in your browser’s developer tools. These errors often provide valuable clues about the source of the problem.

• Official Documentation: Refer to the official Core-JS documentation and issue tracker for known bugs and solutions.

Integrating with other libraries

Generally, Core-JS integrates well with most other JavaScript libraries. However, be mindful of potential conflicts:

• Polyfill Overlap: Avoid including multiple libraries that provide polyfills for the same features. This can lead to conflicts and unexpected behavior. If you’re using a framework or library that already includes some polyfills (like React or Angular), carefully assess whether you need to include additional Core-JS modules.

• Version Compatibility: Check for compatibility between Core-JS and other libraries. Using incompatible versions can cause unexpected issues.

• Testing: Thoroughly test your application after integrating Core-JS with other libraries to ensure everything works as expected.

Performance Considerations

While Core-JS improves compatibility, its use does have performance implications:

• Bundle Size: Minimize bundle size by importing only the necessary polyfills. The modular approach of Core-JS 3 is crucial for this. Avoid using core-js/stable unless absolutely necessary.

• Runtime Overhead: Polyfills inherently add runtime overhead. However, this overhead is generally minimal for modern browsers, where most features are already natively supported. The performance impact is typically far outweighed by the benefits of consistent cross-browser functionality.

• Optimization: Use code splitting and other optimization techniques to further improve performance, especially in large applications.

• Profiling: For performance-critical applications, use profiling tools to identify any performance bottlenecks related to Core-JS.

Contributing to Core-JS

Core-JS is an open-source project, and contributions are welcome! Before contributing, review the project’s contribution guidelines on its GitHub repository. Contributions may include:

• Bug fixes: Report bugs and provide fixes for existing issues.

• New polyfills: Add polyfills for missing ECMAScript features or improve existing ones.

• Documentation improvements: Improve the documentation to make it clearer and more comprehensive.

• Testing: Write and maintain comprehensive tests to ensure the quality of the library.

Follow the project’s established workflow and coding style for your contributions to be considered. Engage with the community to discuss your proposed changes before submitting pull requests.

Appendix

Glossary of Terms

• Polyfill: A piece of code (usually JavaScript) that provides the functionality of a newer specification to older browsers or environments that don’t natively support it. It simulates the behavior of a missing feature.

• Transpiler: A tool that converts source code written in one programming language into another programming language. Often used to convert modern JavaScript code to code compatible with older browsers.

• Tree-shaking: A build optimization technique that removes unused code from the final bundle. This is especially important for minimizing the size of JavaScript applications.

• Bundle: The combined and optimized JavaScript code produced by a bundler, ready for deployment to a web browser.

• ESM (ECMAScript Modules): The standard module system for JavaScript.

• SemVer (Semantic Versioning): A system for assigning version numbers to software that indicates the nature of changes between versions (major, minor, patch).

• API (Application Programming Interface): A set of rules and specifications that software programs can follow to communicate with each other.

Browser Compatibility Table

Note: This is a simplified example. A complete table would list many more features and versions. Refer to the official Core-JS documentation for the most up-to-date and comprehensive browser compatibility information. The symbols ✅ and ❌ represent support and lack of support, respectively. Partial support might indicate that only a subset of the feature is implemented natively.

Changelog

Refer to the official Core-JS repository (usually on GitHub) for the complete changelog. The changelog will detail all changes, bug fixes, new features, and other relevant information for each release.

License Information

Core-JS is typically licensed under the MIT License. Check the official repository’s LICENSE file for the exact terms and conditions. The MIT License generally grants broad permissions to use, modify, and distribute the software.

Community and Support Resources

• Official Website/Documentation: The official website or documentation for Core-JS is the primary source for information.

• GitHub Repository: The GitHub repository is the central location for the source code, issue tracker, and community discussion.

• Issue Tracker: Use the issue tracker on the GitHub repository to report bugs, request features, and get help with problems.

• Community Forums (if applicable): Check for official or community forums dedicated to Core-JS for discussions and support. The official GitHub repository’s issues section often acts as a de facto forum.

Remember to always check the official Core-JS website and repository for the most up-to-date information on community resources and support.