Middleware for Koa servers that transforms standard JavaScript modules to earlier versions of JavaScript and/or AMD modules (inlining loader script @polymer/esm-amd-loader into the HTML), for use with older browsers.
Consider an HTML file containing the following inline JavaScript module:
<script type="module">
import {someFunction} from './some-module.js';
someFunction();
</script>The koa-esm-to-amd middleware would transform that HTML code to something like the following:
<script>
// An inline loader script from `@polymer/esm-amd-loader` package
// which adds the `define` function used below.
</script>
<script>
define(["./some-module.js"], function (someModule) {
someModule.someFunction();
});
</script>Because this is middleware, you can use it in a simple static file server as well with a proxy server. This makes it possible to use in front of a test server such as the one karma starts up. (See koa-karma-proxy for examples.)
Note: HTML and JavaScript are parsed on every request for those content-types, it is intended for use in development context to facilitate build-free testing/iteration as opposed to in a high volume production web server.
By default, a set of babel transform plugins are chosen based on the known capabilities of the browser/user-agent identified in the Koa Context for the request.
When the downstream server returns HTML content, it is scanned for module script tags (e.g. <script type="module">). Any src attribute values are appended with the __esmTransform query parameter. The query parameter is added because the middleware needs to distinguish between scripts that are being imported as a module vs a traditional script and this can't necessarily be determined by looking at the script itself.
Inline module script content and URLs with the __esmTransform query parameter have their import specifiers appended with the __esmTransform to indicate the requested content should be treated as a module and compiled with the selected babel plugins.
Depending on plugins being used, certain support scripts will also be inlined into the HTML, such as @polymer/esm-amd-loader and regenerator-runtime.
babelPlugins: Either an Array of babel plugins (e.g.[require('@babel/plugin-transform-modules-amd')]) or a Function that takes a Koa Context and returns an Array of babel plugins(ctx) => []. Providing a value for this option will override the default behavior of the middleware's capabilities-based babel plugin selection.exclude: An array of requested paths or minimatch based patterns to match requested paths that should be excluded from any process/rewriting by the middleware.queryParam: You can redefine the appended query parameter string from__esmTransformas something else.logger: Middleware will calldebug,info,warnanderrormethods onconsoleto log events. If you use a different logger for your application, provide it here.logLevel: Set a minimum level for events to be logged to override the default level ofinfo.