dimport

    1.0.0 • Public • Published

    dimport Build Status

    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 <script type=module /> 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 😢

    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.



    Modes

    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.

    Usage

    Don't miss the /examples directory ✨

    It's possible to use dimport in a variety of ways!

    The simplest way is to connect a few <script/> tags to unpkg.com:

    <!-- Load the "module" version on browsers that can support it. -->
    <script type="module" src="https://unpkg.com/dimport?module" data-main="/bundle.js"></script>
     
    <!-- Load the "nomodule" version on older browsers – acts as fallback! -->
    <script type="nomodule" src="https://unpkg.com/dimport/nomodule" data-main="/bundle.js"></script>

    In the sample above, a browser will automatically choose which script type to parse.
    This means the two scripts can live side-by-side without loading your application twice!
    Finally, the same application file (bundle.js) 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 <script/> caller also wants it to load a file.
    Alternatively, dimport can load an inline script from its caller!

    <!-- We can use any "mode" here, but choosing only 1 for simplicity -->
    <script src="https://unpkg.com/dimport/nomodule">
      // Notice that we can use `import` inside a script without "type=module"
      import { h, render } from 'https://unpkg.com/preact?module';
     
      render(
        h('h1', null, 'Hello world'),
        document.body
      );
    </script> 

    Finally, dimport is available for programmatic use and/or usable within your bundle (via Webpack or Rollup)

    $ npm install --save dimport
    
    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(...);

    API – Programmatic

    dimport(url)

    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()

    Browser Support

    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
    import()
    native
    dimport
    module
    dimport
    nomodule
    dimport
    legacy
    Chrome 61 63 61 42 👍*
    Safari 10.1 11.1 10.1 10.1 👍*
    Firefox 60 67 60 39 👍*
    Edge 16 16 14 👍*
    IE 7 *

    * Indicates support with Promise polyfill supplied

    Prior Art

    • 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.

    License

    MIT © Luke Edwards

    Install

    npm i dimport

    DownloadsWeekly Downloads

    84,509

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    21.7 kB

    Total Files

    10

    Last publish

    Collaborators

    • lukeed