dev/core#4279 - Add support for ECMAScript Modules (ESM, part 1)

[totten]

Overview

This adds support for loading ECMAScript 6 Modules (ESM's). ESMs are Javascript files with additional support for the keywords import and export. Basic ESM support has been provided by most web-browsers since ~2017.

(This is the first part of https://lab.civicrm.org/dev/core/-/issues/4279. The second part will be a subsequent PR.)

Before

You can add basic Javascript files:

Civi::resources()->addScript('doStuff();');
Civi::resources()->addScriptFile('my_extension', 'js/foo.js');
Civi::resources()->addScriptUrl('https://example.com/bar.js');

But this will not work with ESMs.

After

You can use the addModule() methods for ESMs:

Civi::resources()->addModule('import doStuff from \'./do-stuff.js\'; doStuff();');
Civi::resources()->addModuleFile('my_extension', 'js/foo.js');
Civi::resources()->addModuleUrl('https://example.com/bar.js');

Additionally, since an ESM is a special kind of Javascript file, you can also use the addScript() method. However, this requires the flag ['esm' => TRUE].

Civi::resources()->addScript('import doStuff from \'./do-stuff.js\'; doStuff();', ['esm' => TRUE]);
Civi::resources()->addScriptFile('my_extension', 'js/foo.js', ['esm' => TRUE]);
Civi::resources()->addScriptUrl('https://example.com/bar.js', ['esm' => TRUE]);

Comments

I've included some basic unit-tests for addModule(), etc.

To see them in action, you can use this example extension: https://github.com/totten/esmdemo/

[civibot]

No issue was found matching the number given in the pull request title. Please check the issue number.

[civibot]

(Standard links)

• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[colemanw]

This seems straightforward enough for @totten to merge-on-pass once he's happy with it.