https://github.com/polymer/koa-esm-transform
Middleware for Koa servers that transforms standard JavaScript modules to AMD modules for use with older browsers that don't support modules natively.
https://github.com/polymer/koa-esm-transform
Last synced: 11 months ago
JSON representation
Middleware for Koa servers that transforms standard JavaScript modules to AMD modules for use with older browsers that don't support modules natively.
- Host: GitHub
- URL: https://github.com/polymer/koa-esm-transform
- Owner: Polymer
- License: bsd-3-clause
- Created: 2019-06-25T23:26:52.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-04-09T13:39:32.000Z (about 1 year ago)
- Last Synced: 2025-05-02T02:38:36.288Z (about 1 year ago)
- Language: TypeScript
- Size: 522 KB
- Stars: 10
- Watchers: 13
- Forks: 3
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```html
import {someFunction} from './some-module.js';
someFunction();
```
The koa-esm-to-amd middleware would transform that HTML code to something like the following:
```html
// An inline loader script from `@polymer/esm-amd-loader` package
// which adds the `define` function used below.
define(["./some-module.js"], function (someModule) {
someModule.someFunction();
});
```
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.)
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. ``). 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](https://www.npmjs.com/package/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`.