Jsenv node module import map

Generate importMap for a project node modules.

Table of contents

• Presentation
• How it works
• Code example
• API
• Concrete example
  • Step 1 - Setup project
  • Step 2 - Install project dependencies
  • Step 3 - Generate project importMap
• Custom node module resolution
• Installation

Presentation

@jsenv/node-module-import-map generates importMap for your project node_modules.
— see importMap spec

How it works

Reads package.json and recursively try to find your dependencies.

Be sure node modules are on your filesystem because we'll use the filesystem structure to generate the importMap. For that reason, you must use it after npm install or anything that is responsible to generate the node_modules folder and its content on your filesystem.

Code example

Here is code example using @jsenv/node-module-import-map to create an importMap.json.

const { generateImportMapForProjectPackage } = require("@jsenv/node-module-import-map")

generateImportMapForProjectPackage({
  projectDirectoryPath: __dirname,
  includeDevDependencies: true,
  importMapFile: true,
  importMapFileRelativePath: "./importMap.json",
})

For more information check the api documentation.

Concrete example

This part explains how to setup a real environment to see @jsenv/node-module-import-map in action. It reuses a preconfigured project where you can generate import map file.

Step 1 - Setup project

git clone git@github.com:jsenv/jsenv-node-module-import-map.git

Step 2 - Install project dependencies

cd ./jsenv-node-module-import-map/docs/basic-project

If you never configured npm authentification on github registry see Configure npm authentification on github registry first.

npm install

Step 3 - Generate project importMap

Running command below will generate import map file at docs/basic-project/importMap.json.

node ./generate-import-map.js

Custom node module resolution

@jsenv/node-module-import-map uses a custom node module resolution.
— see node module resolution on node.js

It behaves as Node.js with one big change:

A node module will not be found if it is outside your project folder.

We do this because importMap are used on the web where a file outside project folder would fail.

And here is why:

You have a server at https://example.com serving files inside /Users/you/project.
Your project uses a file outside of your project folder like /Users/you/node_modules/whatever/index.js.

From a filesystem perspective we could find file using ../node_modules/whatever/index.js.
For a web client however ../node_modules/whatever/index.js resolves to https://example.com/node_modules/whatever/index.js. Server would be requested at that url searching for /Users/you/project/node_modules/whatever/index.js instead of /Users/you/node_modules/whatever/index.js.

In practice it does not impact you because node modules are inside your project folder. If not, explicitely write your dependencies in your package.json and run npm install.

Installation

If you never installed a jsenv package, read Installing a jsenv package before going further.

This documentation is up-to-date with a specific version so prefer any of the following commands

npm install --save-dev @jsenv/node-module-import-map@8.4.1

yarn add --dev @jsenv/node-module-import-map@8.4.1