Skip to content

Middleware for Koa servers that transforms standard JavaScript modules to AMD modules for use with older browsers that don't support modules natively.

License

Notifications You must be signed in to change notification settings

Polymer/koa-esm-transform

Repository files navigation

koa-esm-transform

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.

How it works

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.

Options

  • 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 __esmTransform as something else.
  • logger: Middleware will call debug, info, warn and error methods on console to 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 of info.

About

Middleware for Koa servers that transforms standard JavaScript modules to AMD modules for use with older browsers that don't support modules natively.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published