@jsenv/node-module-import-map
Generate importmap for node_modules.
Last updated 12 days ago by dmail .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @jsenv/node-module-import-map 
SYNC missed versions from official npm registry.

node-module-import-map

Generate importmap for node_modules.

github package npm package github ci codecov coverage

Table of contents

Presentation

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

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

import { generateImportMapForProjectPackage } from "@jsenv/node-module-import-map"

generateImportMapForProjectPackage({
  projectDirectoryUrl: "file:///directory",
  includeDevDependencies: true,
  importMapFile: true,
  importMapFileRelativeUrl: "./importMap.json",
})

@jsenv/node-module-import-map can also be required.

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

Installation

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

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 basic project

git clone https://github.com/jsenv/jsenv-node-module-import-map.git
cd ./jsenv-node-module-import-map/docs/basic-project
npm install

Step 2 - Generate project importMap

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

node ./generate-import-map.js

Documentation

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.

generateImportMapForProjectPackage

generateImportMapForProjectPackage is an async function returning an importMap object.

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

const importMap = await generateImportMapForProjectPackage({
  projectDirectoryUrl: __dirname,
  includeDevDependencies: true,
  importMapFile: false,
  importMapFileRelativeUrl: "./importMap.json",
  importMapFileLog: true,
})

— source code at src/generateImportMapForProjectPackage.js.

projectDirectoryUrl

projectDirectoryUrl parameter is a string url leading to a folder with a package.json. This parameters is required and accepted values are documented in https://github.com/jsenv/jsenv-util#assertAndNormalizeDirectoryUrl

includeDevDependencies

includeDevDependencies parameter is a boolean controling if devDependencies are included in the generated importMap. This parameter is optional with a default value of process.env.NODE_ENV !== "production".

importMapFile

importMapFile parameter is a boolean controling if importMap is written to a file. This parameters is optional with a default value of false.

importMapFileRelativeUrl

importMapFileRelativeUrl parameter is a string controlling where importMap file is written. This parameter is optional with a default value of "./importMap.json".

importMapFileLog

importMapFileLog parameter a boolean controlling if there is log in the terminal when importMap file is written. It is optional with a default value of true.

favoredExports

favoredExports parameter is an array of string representing what conditional export you prefer to pick from package.json. This parameters is optional with a default value of ["import", "node", "require"].

This parameters exists to support conditional exports from Node.js.

— see Conditional export documentation on Node.js

For instance if you want to favor "browser" conditional export use the following value.

["browser"]

Or if you prefer "electron" and fallback to "browser" use the following value.

["electron", "browser"]

When favoredExports is empty or none of favored export matches in a package.json and if there is a "default" conditional export specified in the package.json it is used and appears in the generated importmap.

Current Tags

  • 11.0.1                                ...           latest (12 days ago)

47 Versions

  • 11.0.1                                ...           12 days ago
  • 11.0.0                                ...           24 days ago
  • 10.4.0                                ...           a month ago
  • 10.3.0                                ...           a month ago
  • 10.2.1                                ...           a month ago
  • 10.2.0                                ...           a month ago
  • 10.1.0                                ...           a month ago
  • 10.0.1                                ...           a month ago
  • 10.0.0                                ...           2 months ago
  • 9.4.0                                ...           2 months ago
  • 9.3.0                                ...           2 months ago
  • 9.2.0                                ...           2 months ago
  • 9.1.0                                ...           2 months ago
  • 9.0.0                                ...           3 months ago
  • 8.6.0                                ...           3 months ago
  • 8.5.0                                ...           3 months ago
  • 8.4.1                                ...           4 months ago
  • 8.4.0                                ...           4 months ago
  • 8.3.0                                ...           4 months ago
  • 7.1.0                                ...           5 months ago
  • 7.0.0                                ...           5 months ago
  • 6.4.0                                ...           6 months ago
  • 6.3.0                                ...           6 months ago
  • 6.2.0                                ...           6 months ago
  • 6.1.0                                ...           6 months ago
  • 6.0.0                                ...           6 months ago
  • 5.1.0                                ...           6 months ago
  • 5.0.0                                ...           6 months ago
  • 4.4.0                                ...           6 months ago
  • 4.3.0                                ...           6 months ago
  • 4.2.0                                ...           6 months ago
  • 4.1.0                                ...           6 months ago
  • 4.0.0                                ...           6 months ago
  • 3.4.0                                ...           6 months ago
  • 3.3.0                                ...           6 months ago
  • 3.2.0                                ...           6 months ago
  • 3.1.0                                ...           6 months ago
  • 3.0.0                                ...           7 months ago
  • 2.1.0                                ...           7 months ago
  • 2.0.0                                ...           8 months ago
  • 1.7.0                                ...           8 months ago
  • 1.5.0                                ...           9 months ago
  • 1.4.0                                ...           9 months ago
  • 1.3.0                                ...           9 months ago
  • 1.2.0                                ...           9 months ago
  • 1.1.0                                ...           9 months ago
  • 1.0.0                                ...           9 months ago
Maintainers (2)
Downloads
Today 0
This Week 0
This Month 20
Last Day 0
Last Week 20
Last Month 217
Dependencies (4)

Copyright 2014 - 2017 © taobao.org |