|
| 1 | +# koa-esm-transform |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +Consider an HTML file containing the following inline JavaScript module: |
| 6 | + |
| 7 | +```html |
| 8 | +<script type="module"> |
| 9 | +import {someFunction} from './some-module.js'; |
| 10 | +someFunction(); |
| 11 | +</script> |
| 12 | +``` |
| 13 | + |
| 14 | +The koa-esm-to-amd middleware would transform that HTML code to something like the following: |
| 15 | + |
| 16 | +```html |
| 17 | +<script> |
| 18 | +// An inline loader script from `@polymer/esm-amd-loader` package |
| 19 | +// which adds the `define` function used below. |
| 20 | +</script> |
| 21 | +<script> |
| 22 | +define(["./some-module.js"], function (someModule) { |
| 23 | + someModule.someFunction(); |
| 24 | +}); |
| 25 | +</script> |
| 26 | +``` |
| 27 | + |
| 28 | +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](https://github.com/Polymer/koa-karma-proxy) for examples.) |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +## How it works |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +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. |
| 37 | + |
| 38 | +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. |
| 39 | + |
| 40 | +Depending on plugins being used, certain support scripts will also be inlined into the HTML, such as `@polymer/esm-amd-loader` and `regenerator-runtime`. |
| 41 | + |
| 42 | +## Options |
| 43 | + |
| 44 | +- `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. |
| 45 | +- `exclude`: An array of requested paths or [minimatch](https://www.npmjs.com/package/minimatch) based patterns to match requested paths that should be excluded from any process/rewriting by the middleware. |
| 46 | +- `queryParam`: You can redefine the appended query parameter string from `__esmTransform` as something else. |
| 47 | +- `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. |
| 48 | +- `logLevel`: Set a minimum level for events to be logged to override the default level of `info`. |
0 commit comments