Merge pull request #17 from jsenv/import-map-extension

importmap extension + custom import map file

Author: dmail

.eslintrc.cjs

@@ -2,6 +2,7 @@ const { createEslintConfig } = require("@jsenv/eslint-config")
 
 const config = createEslintConfig({
   projectDirectoryUrl: __dirname,
+  importMapFileRelativeUrl: "./import-map.importmap",
   importResolutionMethod: "import-map",
 })
 

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       matrix:
         os: [windows-latest, ubuntu-latest]
-        node: [13.12.0]
+        node: [14.5.0]
     runs-on: ${{ matrix.os }}
     name: test on ${{ matrix.os }} and node ${{ matrix.node }}
     env:
@@ -49,7 +49,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v1
         with:
-          node-version: "13.x"
+          node-version: "14.x"
       - name: npm install
         run: |
           npm config set //npm.pkg.github.com/:_authToken ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -5,6 +5,8 @@
 /docs/basic-project/package-lock.json
 /docs/basic-project/yarn.lock
 /node_modules/
+/test/generateImportMapForProject/**/*.importmap
+/import-map.importmap
 /jsconfig.json
 /package-lock.json
 /secrets.json

.npmrc

@@ -1,2 +1 @@
-save-exact=true
-@jsenv:registry=https://npm.pkg.github.com
+save-exact=true

.prettierignore

@@ -2,10 +2,8 @@
 /coverage/
 /dist/
 /docs/basic-project/node_modules/
-/docs/basic-project/importMap.json
 /docs/basic-project/package-lock.json
 /node_modules/
-/importMap.json
 /jsconfig.json
 /package-lock.json
 /package.json

.vscode/launch.json

@@ -7,7 +7,7 @@
       "request": "launch",
       "protocol": "inspector",
       "program": "${file}",
-      "runtimeVersion": "14.5.0",
+      // "runtimeVersion": "14.5.0",
       "runtimeArgs": [
         "--unhandled-rejections=strict",
         "--experimental-json-modules",

docs/advanced.md

@@ -0,0 +1,77 @@
+# Table of contents
+
+- [generateImportMapForProject](#generateImportMapForProject)
+  - [importMapFile](#importMapFile)
+  - [importMapFileRelativeUrl](#importMapFileRelativeUrl)
+  - [importMapFileLog](#importMapFileLog)
+- [getImportMapFromFile](#getImportMapFromFile)
+  - [importMapFileUrl](#importMapFileUrl)
+
+# generateImportMapForProject
+
+`generateImportMapForProject` is an async function receiving an array of promise resolving to importmaps. It awaits for every importmap, compose them into one and write it into a file.
+
+> This function is meant to be responsible of generating the final importMap file that a project uses.
+
+For example code below will generate an import map from node_modules + a file + an inline importmap.
+
+```js
+import {
+  getImportMapFromNodeModules,
+  getImportMapFromFile,
+  generateImportMapForProject,
+} from "@jsenv/node-module-import-map"
+
+const projectDirectoryUrl = new URL("./", import.meta.url)
+const customImportMapFileUrl = new URL("./import-map-custom.importmap", projectDirectoryUrl)
+
+await generateImportMapForProject(
+  [
+    getImportMapFromNodeModules({
+      projectDirectoryUrl,
+      projectPackageDevDependenciesIncluded: true,
+    }),
+    getImportMapFromFile(customImportMapFileUrl),
+    {
+      imports: {
+        foo: "./bar.js",
+      },
+    },
+  ],
+  {
+    projectDirectoryUrl,
+    importMapFileRelativeUrl: "./import-map.importmap",
+  },
+)
+```
+
+— source code at [src/generateImportMapForProject.js](../src/generateImportMapForProject.js).
+
+## importMapFile
+
+`importMapFile` parameter is a boolean controling if importMap is written to a file. This parameters is optional and enabled by default.
+
+## importMapFileRelativeUrl
+
+`importMapFileRelativeUrl` parameter is a string controlling where importMap file is written. This parameter is optional and by default it's `"./import-map.importmap"`.
+
+## importMapFileLog
+
+`importMapFileLog` parameter a boolean controlling if there is log in the terminal when importMap file is written. This parameter is optional and by default it's enabled.
+
+# getImportMapFromFile
+
+`getImportMapFromFile` is an async function reading importmap from a file.
+
+```js
+import { getImportMapFromFile } from "@jsenv/node-module-import-map"
+
+const importMapFileUrl = new URL("./import-map.importmap", import.meta.url)
+const importMap = await getImportMapFromFile(importMapFileUrl)
+```
+
+— source code at [src/getImportMapFromFile.js](../src/getImportMapFromFile.js).
+
+## importMapFileUrl
+
+`importMapFileUrl` parameter a string or an url leading to the importmap file. This parameter is **required**.

docs/api.md

@@ -1,8 +1,9 @@
-const { generateImportMapForProjectPackage } = require("@jsenv/node-module-import-map")
+import { getImportMapFromNodeModules } from "@jsenv/node-module-import-map"
 
-generateImportMapForProjectPackage({
+const importMap = await getImportMapFromNodeModules({
   projectDirectoryUrl: __dirname,
-  includeDevDependencies: true,
-  importMapFile: true,
-  importMapFileRelativeUrl: "./importMap.json",
+  projectPackageDevDependenciesIncluded: true,
+  importMapFileRelativeUrl: "./import-map.importmap",
 })
+
+console.log(importMap)

docs/basic-project/generate-import-map.js

@@ -2,10 +2,14 @@
   "name": "whatever",
   "version": "0.0.1",
   "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=14.0.0"
+  },
   "scripts": {
     "generate-import-map": "node ./generate-import-map.js"
   },
   "devDependencies": {
-    "@jsenv/node-module-import-map": "10.1.0"
+    "@jsenv/node-module-import-map": "12.0.0-alpha.0"
   }
 }