Webpack Import-Map Plugin

A plugin for Webpack to generate an import-map for bundled & emitted files. Heavily based on webpack-manifest-plugin.
Currently only generates top-level maps, scoped maps are not supported yet.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

• About the Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

This plugin allows you to use filename hashing, etc. and automatically generate an import-map to use standalone, or as a patch file for something like import-map-deployer.

Two main use cases are generating an import-map that allows for using hashes in filenames, to make cache-busting easy, or to generate a delta/patch file to use in a deployment pipeline.

Built With

• JavaScript
• Lots of coffee

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

• Node >= 10.x
• Webpack >= 2.x
• Some knowledge of import-maps

Installation

1. Add the devDependency to your project

npm i -D webpack-import-map-plugin

2. Add the plugin in your webpack config's plugins and configure it

// webpack.config.js
const ImportMapWebpackPlugin = require('webpack-import-map-plugin');

Demo

// with a Webpack 4 config like:
config.entry = { entryName: 'entry-file.js' };
config.output.filename = '[name].[contenthash:8].js';

// Add to plugins
new ImportMapWebpackPlugin({
    filter: x => {
        return ['entryName.js'].includes(x.name);
    },
    transformKeys: filename => {
        if (filename === 'entryName.js') {
            return '@my-super-scope/out-file';
        }
    },
    fileName: 'import-map.json',
    baseUrl: 'https://super-cdn.com/'
});
// output import-map.json
{
    "imports": {
        "@my-super-scope": "https://super-cdn.com/entryName.12345678.js"
    }
}

Usage

Configuration Options

The configuration object is very similar to webpack-manifest-plugin but not exactly the same. Some sensible defaults are set for most options, though YMMMV.

include

A filter, or array of filters to run on the entry filenames that should be included in the resulting import-map. Strings will match exactly, run in order provided. A falsy value will include all files. Note: Run before exclude.

• type: RegExp | string
• default: ''

exclude

A filter, or array of filters to run on the entry filenames that should be excluded in the resulting import-map. Strings will match exactly, run in order provided. A falsy value will not exclude any files. Note: Run after include.

• type: RegExp | string
• default: ''

filter

A more complex filter function that receives the whole file object from webpack and returns a falsy value to exclude the file from the resulting import map. Note: Run after include and exclude.

• type: Function(FileDescriptor): boolean
• default: null

transformKeys

A function run on the filename after the filters that allow you to generate a "key" for your import-map. You can strip key extensions, or rewrite with this function.You probably want to implement this option.

• type: Function(string): string
• default: null

transformValues

A function run on the emitted asset file path (i.e. /dist/main.hash.js). You could use this function to rewrite prefixed paths, etc.

• type: Function(string): string
• default: null

baseUrl

A string url to to prefix the values with. A good usage would be prepending a cdn address or placeholder to rewrite in a pipeline process. Note: Run after transformValues.

• type: string
• default: null

fileName

The output filename, emitted to the output directory.

• type: string
• default: 'import-map.json'

writeToFileEmit

If set to true will emit to build folder and memory in combination with webpack-dev-server.

• type: boolean
• default: false

generate

The function that generates the resulting import-map. This is where you could implement scopes, etc.

• type: Function(Object, FileDescriptor, string[]): Object
• default:

(seed, files, entrypoints) => files.reduce(function (manifest, file) {
    manifest[file.name] = file.path;
    return manifest;
}, seed);

seed

A cache of key/value pairs to used to seed the import-map. A good use for this would be including libraries/runtimes, or a base import-map for webpack-dev-server debugging.

• type: Object
• default: {}

map

Modify files details before the manifest is created.

• type: Function(FileDescriptor): FileDescriptor
• default: null

sort

Sort files before they are passed to generate.

• type: Function(FileDescriptor): number
• default: null

serialize

The serializing function for the result import-map. Unless you are doing something unique, it's best to leave this as is.

• type: Function(Object): string
• default:

function (manifest) {
    return JSON.stringify(manifest, null, 4);
}

Type: FileDescriptor

FileDescriptor

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please make sure any contributions have proper unit tests and update any relevant documentation.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Zachary Leighton - [email protected]

Project Link: https://github.com/zleight1/webpack-import-map-plugin

Acknowledgements

• Heavily based on webpack-manifest-plugin
• Many thanks to single-spa for a great front-end microservices "meta-framework".
• import-maps