Run ES Module syntax in any browser – even IE!
npm install dimport> Run ES Module syntax (import, import(), and export) in any browser — even IE!
At its core, dimport is a polyfill for ES Module syntax, including dynamic imports!
And with it, you can serve modern ESM-driven application files to any browser.
While browsers _are_ increasing support for JavaScript modules natively, the current landscape is not easy to navigate.
For example, many browsers _do support_ ESM syntax (aka, import and export) within tags; however, not all of these support _dynamic import_ statements since it came later.
In order to leverage the benefits of ESM today, a developer must choose between:
* dropping support for lagging browsers
* complicating their development process
* building and/or distributing multiple versions of their application
* abstaining from shipping ESM syntax at all :cry:
Now, dimport allows the developer to ship ESM today to all browsers without comproimse.
Better yet, the development and distribution processes are simplified, if not unchanged.
PS: Check out the /examples directory~!
---
Important
This module does not convert your ES2015+ syntax into ES5 or below!
While dimport may allow older browsers to parse and interpret the ESM format, it does nothing to make the _contents_ of your file(s) backwards compatible.
---
There are three "versions" of dimport, each of which utilize different APIs and approaches to yield full ESM compatability.
Please note that all modes check for native import() support first and foremost.
This means that dimport won't do anything if it doesn't have to.
#### "module"
> Size (gzip): 675 bytes
> Availablility: UMD, CommonJS, ES Module
> Requires: script[type=module], fetch, Promise, URL
Since _static_ import statements are supported, this mode parses all _dynamic_ import()s and creates temporary script[type=module] tags pointing to the resource's full, canonical URL. Once the temporary script loads, the originating Promise is resolved, returning the contents.
#### "nomodule"
> Size (gzip): 918 bytes
> Availablility: UMD, ES Module
> Requires: fetch, Promise, URL
All import, export, and import() statements are dynamically rewritten to CommonJS modules so that their contents/exports are easily returned.
Any import statements are parsed early, ensuring full canonical URLs, and then the whole file is wrapped in a Promise.all chain, guaranteeing each import its desired module.
#### "legacy"
> Size (gzip): 1143 bytes
> Availablility: UMD, ES Module
> Requires: Promise, XMLHttpRequest
Takes the same approach as "nomodule", but inserts alternatives to fetch and URL.
> Important: You will need to supply your own Promise polyfill for IE support.
> Don't miss the /examples directory :sparkles:
It's possible to use dimport in a variety of ways!
The simplest way is to connect a few tags to unpkg.com:
``html
`
In the sample above, a browser will automatically choose which script type to parse.bundle.js
This means the two scripts can live side-by-side without loading your application twice!
Finally, the _same_ application file () can be used, despite the module-vs-nomodule choice.
You will also notice that the scripts have a data-main="" attribute.
This the path to _your application_ or _your ESM-containing file_ you wish to load.
Once dimport has loaded, it circles back and see that its caller also wants it to load a file.dimport
Alternatively, can load an inline script from its caller!
`html`
Finally, dimport is available for programmatic use and/or usable _within_ your bundle (via Webpack or Rollup)
`
$ npm install --save dimport
`js
import dimport from 'dimport';
// or, without bundling
import dimport from 'https://unpkg.com/dimport?module';
// Pass in URLs or file paths
// ~> like import() usage`
dimport('./foo.js').then(...);
Returns: Promise
Returns a Promise containing the module.
#### url
Type: String
The URL of the script to import.
> Note: Will be transformed into a full URL if not already – see new URL()
The dimport columns yield support for both static and dynamic imports.
> Important: Chart represents ESM syntax only!
Not indicative of ES2015+ syntax usage within your app.
| Browser | import
native |
native | dimport
module | dimport
nomodule | dimport
legacy |
|---------|--------------------|----------------------|-------------------|---------------------|-------------------|
| Chrome | 61 | 63 | 61 | 42 | :+1:* |
| Safari | 10.1 | 11.1 | 10.1 | 10.1 | :+1:* |
| Firefox | 60 | 67 | 60 | 39 | :+1:* |
| Edge | 16 | :x: | 16 | 14 | :+1:* |
| IE | :x: | :x: | :x: | :x: | 7 * |
* _Indicates support with Promise polyfill supplied_
* dynamic-import-ponyfill – The "first version" of dimport – now deprecated.shimport` – Patient zero. Similar to "nomodule" mode. Made it "okay" to rewrite files on the fly.
*
MIT © Luke Edwards