Webpack-import-map-plugin NPM

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

Add the devDependency to your project

npm i -D webpack-import-map-plugin

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.