5.20231.904
5.20231.904

Multiple npm module formats

Wijmo npm packages provide their content in multiple formats, which are combinations of the language version (ES5 or ES2015) and module format (CommonJS or ESM).
Every format in the installed package folder is represented by a separate .js file, referenced by a special field in the package.json file. Modern bundlers like Webpack can use a package file in the preferred format, depending on the bundler configuration.
Bundlers without this capability will use the main field in package.json to resolve module name to a specific .js file. In the Wijmo packages, it is the index.js file which contains the (most compatible) ES5 + CommonJS format.

Below is a list of package.json fields and the corresponding file formats that they represent from the package folder:

  • main: ES5 + CommonJS (index.js)
  • module, esm5, wj-esm5: ES5 + ESM (es5-esm.js)
  • esm2015, es2015, wj-esm2015: ES2015 + ESM (es2015-esm.js)
  • es2015Cjs, wj-es2015Cjs: ES2015 + CommonJS (es2015-commonjs.js)

By default Webpack uses the module field to resolve the package name to a .js file, and if absent, it defaults to the main field. This can be changed using the resolve.mainFields option in the Webpack config, where you can specify your preferences.
You can find more details about this option in the Webpack documentation here.

Because field names are not standardized for all module formats, we provide some alternative names for them found in popular frameworks (mostly in Angular).
Among them we provide Wijmo specific fields, whose names begin with wj-. It's assumed that fields with such names are not used in other packages, so they allow you to define a preferred module format specifically for Wijmo packages, while using other field names for non-Wijmo packages. For example, this setting in a webpack.config.js file will force Webpack to include Wijmo packages in the ES2015 + ESM format, and will only affect Wijmo packages:

resolve: {
    mainFields: ['wj-esm2015', 'module', 'main'],
    ...
},