``js
import lodash from "lodash"
`

The code above is expecting Node.js to "magically" find file corresponding to "lodash". This magic is the node esm resolution algorithm. Other runtimes than Node.js, a browser like Chrome for instance, don't have this algorithm. Executing that code in a browser fetches http://example.com/lodash and likely results in 404 File Not Found from server.

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

`js
import { getImportMapFromProjectFiles, writeImportMapFile } from "@jsenv/node-module-import-map"

const projectDirectoryUrl = new URL("./", import.meta.url)

await writeImportMapFile(
[
getImportMapFromProjectFiles({
projectDirectoryUrl,
}),
],
{
projectDirectoryUrl,
importMapFileRelativeUrl: "./project.importmap",
},
)
`

The code above is written in ESM. You may have to use .mjs extension to run it with Node.js as documented in enabling ESM

`console
node generate-import-map.js
`

`html













`

If you use a bundler or an other tool, be sure it's compatible with import maps. As import map are standard the bundler/tool might be compatible by default or with the help of some plugin/configuration. @jsenv/core seamlessly supports importmap during development, testing and when building for production.

`js
import { getImportMapFromProjectFiles, writeImportMapFile } from "@jsenv/node-module-import-map"

const projectDirectoryUrl = new URL("./", import.meta.url)
const importMapInputs = [
getImportMapFromProjectFiles({
projectDirectoryUrl,
dev: true,
}),
{
imports: {
foo: "./bar.js",
},
},
]

await writeImportMapFile(importMapInputs, {
projectDirectoryUrl,
importMapFileRelativeUrl: "./import-map.importmap",
})
`

implementation

importMapInputs is an array of importmap object or promise resolving to importmap objects. This parameter is optional and is an empty array by default.

> When importMapInputs is empty a warning is emitted and writeImportMapFile write an empty importmap file.

importMapFile parameter is a boolean controling if importMap is written to a file. This parameters is optional and enabled by default.

importMapFileRelativeUrl parameter is a string controlling where importMap file is written. This parameter is optional and by default it's "./import-map.importmap".

`js
import { getImportMapFromProjectFiles } from "@jsenv/node-module-import-map"

const importMap = await getImportMapFromProjectFiles({
projectDirectoryUrl: new URL("./", import.meta.url),
dev: false,
runtime: "browser",
})
`

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

implementation

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

dev parameter is a boolean indicating if the importmap will be used for development or production. This parameter is optional and by default it's disabled.

When enabled the following happens:

1. devDependencies declared in your package.json are included in the generated importMap.
2. "development" is favored over "production" in package.json conditions

runtime parameter is a string indicating where the importmap will be used. This parameter is optional with a default of "browser".

When runtime is "browser", "browser" is favored over "node" in package.json conditions.

When it is "node", "node" is favored.

treeshakeMappings parameter is a boolean controlling if mappings will be treeshaked according to the import found in your files.

When enabled, only the mappings actually used by your files will be generated. It will drastically decrease the importmap file size. This is the default behaviour as long as dev parameter is disabled.

When disabled, all mappings needed for node _esm module resolution_ will be generated. During development, you can start/stop using a mapping at any time. In that case it's more convenient to keep unused mappings in the generated importmap. Consequently treeshakeMappings parameter is disabled when dev parameter is enabled.

initialImportMap parameter is an importMap object. This parameter is optional and by default it's an empty object.

You can use this parameter to provide mappings that are not already in your package.json.

`js
import { getImportMapFromProjectFiles } from "@jsenv/node-module-import-map"

const importMap = await getImportMapFromProjectFiles({
projectDirectoryUrl: new URL("./", import.meta.url),
initialImportMap: {
imports: {
foo: "./bar.js",
},
},
})

console.log(importMap.imports.foo) // "./bar.js"
`

`js
import { getImportMapFromFile } from "@jsenv/node-module-import-map"

const importMap = await getImportMapFromFile({
projectDirectoryUrl: new URL("./", import.meta.url),
importMapRelativeUrl: "./import-map.importmap",
})
`

implementation

importMapFileRelativeUrl parameter is an url relative to projectDirectoryUrl leading to the importmap file. This parameter is required.

`js
import { foo } from "./file"
`

`js
import { writeImportMapFile } from "@jsenv/node-module-import-map"

await writeImportMapFile(
[
{
imports: {
"src/": "./src/",
},
},
],
{
projectDirectoryUrl: new URL("./", import.meta.url),
jsConfigFile: true,
},
)
`

Code above would result into the following jsconfig.json file

`json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"src/": ["./src/"]
}
}
}
`