import-maps-webpack-plugin
    TypeScript icon, indicating that this package has built-in type declarations

    0.6.8 • Public • Published

    npm node chat size

    import-maps-webpack-plugin

    The import-maps-webpack-plugin module for declaring / using import maps. These externals will not be bundled in directly, but only be loaded if not already present. 🚀

    It follows pretty much the parcel-plugin-import-maps implementation.

    Getting Started

    Installation

    To begin, you'll need to install import-maps-webpack-plugin:

    npm install import-maps-webpack-plugin --save-dev

    Import Maps Declaration

    You can now add a new key to your package.json: importmap. The key can either hold an importmap structure (see specification) or a reference to a valid JSON file holding the structure.

    Example for the containing the structure in the package.json:

    {
      "name": "my-app",
      "version": "1.0.0",
      "devDependencies": {
        "webpack": "4.x",
        "import-maps-webpack-plugin": "latest"
      },
      "importmap": {
        "imports": {
          "/app/helper": "node_modules/helper/index.mjs",
          "lodash": "./node_modules/lodash-es/lodash.js"
        }
      }
    }

    Alternative version:

    {
      "name": "my-app",
      "version": "1.0.0",
      "devDependencies": {
        "webpack": "4.x",
        "import-maps-webpack-plugin": "latest"
      },
      "importmap": "./my-imports.json"
    }

    where the my-imports.json looks like

    {
      "imports": {
        "/app/helper": "node_modules/helper/index.mjs",
        "lodash": "./node_modules/lodash-es/lodash.js"
      }
    }

    Loading the Import Maps

    With this equipped the given modules are loaded asynchronously at the beginning of the application. If multiple applications with import maps are loaded then the dependencies are either shared or not shared depending on their individual hashes.

    This ensures proper dependency isolation while still being able to share what makes sense to be shared.

    Most importantly, the plugin allows you to place scripts from other locations easily without bundling them in:

    {
      "imports": {
        "lodash": "https://cdn.jsdelivr.net/npm/lodash@4.17.15/lodash.min.js"
      }
    }

    For proper IDE (or even TypeScript) usage we still advise to install the respective package or at least its bindings locally.

    Using Asynchronous Imports

    The required import maps are loaded at startup asynchronously. Therefore, you'd need to wait before using them.

    Unfortunately, in the current version this cannot be done implicitly (reliably), even though its desired for the future.

    Right now the only way is to change code like (assumes lodash is used from an import map like above)

    //app.js
    import * as _ from 'lodash';
    
    const _ = require('lodash');
    
    export const partitions = _.partition([1, 2, 3, 4], n => n % 2);
    });

    to be

    //app.js
    require('importmap').ready().then(() => {
      const _ = require('lodash');
      return {
        partitions: _.partition([1, 2, 3, 4], n => n % 2),
      };
    });

    or, alternatively (more generically),

    //index.js
    module.exports = require('importmap').ready().then(() => require('./app'));
    
    //app.js
    import * as _ from 'lodash';
    
    const _ = require('lodash');
    
    export const partitions = _.partition([1, 2, 3, 4], n => n % 2);
    });

    You could also trigger the loading already in the beginning, i.e.,

    //app.js
    require('importmap');
    
    // ...
    //other.js
    require('importmap').ready('lodash').then(() => {
      // either load or do something with require('lodash')
    });

    where we use ready with a single argument to determine what package should have been loaded to proceed. This is the deferred loading approach. Alternatively, an array with multiple package identifiers can be passed in.

    Options

    (No options yet.)

    Examples

    The following examples show how one might use import-maps-webpack-plugin and what the result would be.

    Including Import Maps Support

    Using the plugin is as simple as just importing the ImportMapsWebpackPlugin class and providing an instance of it to the webpack configuration.

    Example:

    import { ImportMapsWebpackPlugin } from 'import-maps-webpack-plugin';
    
    module.exports = {
      // ... standard webpack
      plugins: [
        new ImportMapsWebpackPlugin(),
      ],
    };

    This will the importmap virtual module and its API. All dependencies are then specified as via the given import maps specification.

    Contributing

    Contributions in any form are appreciated and much welcome!

    Just make sure to post an issue or reach out to me on Gitter before starting actual work on anything. It really helps to avoid problems.

    License

    This plugin is released using the MIT license.

    Install

    npm i import-maps-webpack-plugin

    DownloadsWeekly Downloads

    3,437

    Version

    0.6.8

    License

    MIT

    Unpacked Size

    21.3 kB

    Total Files

    12

    Last publish

    Collaborators

    • florianrappl