@eik/esbuild-plugin 2.0.0-next.1 → 2.0.0

package/README.md

@@ -1,48 +1,43 @@
 # @eik/esbuild-plugin
 
-ESBuild plugin for loading import maps from a [Eik server](https://eik.dev/) and applying the mapping to ECMAScript modules in preparation for upload to the same server.
+[esbuild](https://esbuild.github.io/) plugin for [build-time import mapping with Eik](https://eik.dev/docs/guides/esbuild).
 
 ## Installation
 
 ```bash
-$ npm install @eik/esbuild-plugin
+npm install --save-dev esbuild @eik/esbuild-plugin
 ```
 
 ## Usage
 
 ```js
-import * as eik from '@eik/esbuild-plugin';
-import esbuild from 'esbuild';
-
-await eik.load();
-
-await esbuild.build({
-    entryPoints: ['./src/app.js'],
-    bundle: true,
-    format: 'esm',
-    target: ['esnext'],
-    plugins: [eik.plugin()],
+import * as eik from "@eik/esbuild-plugin";
+import esbuild from "esbuild";
+
+const options = /** @type {esbuild.BuildOptions}*/ ({
+	entryPoints: ["./src/index.js"],
+	outdir: "./public",
+	format: "esm",
+	platform: "browser",
+	target: ["es2017"],
+	bundle: true,
+	sourcemap: true,
 });
-```
-
-## Description
 
-This plugin will read a local Eik config file (`eik.json`) and download the import maps from the Eik server defined in the config. The downloaded import maps will then be applied to the ECMAScript modules being processed.
-
-### Plugin result
-
-Bundles will have bare imports mapped to absolute URLs. 
-
-Ie. Something like this...
-
-```js
-import { LitElement, html, css } from "lit-element";
-```
-
-Will be mapped to something like this...
-
-```js
-import { LitElement, html, css } from "https://cdn.eik.dev/lit-element/v2";
+const watch = process.argv.includes("--dev");
+if (watch) {
+	let ctx = await esbuild.context(options);
+	await ctx.watch();
+	console.log("[esbuild] watching...");
+} else {
+	// Use the Eik plugin to to import mapping for the production build
+	// Load the import maps listed in eik.json from the Eik server
+	await eik.load();
+	await esbuild.build({
+		...options,
+		plugins: [eik.plugin()],
+	});
+}
 ```
 
 ## API
@@ -53,11 +48,11 @@ This module has the following API:
 
 Loads an Eik configuration or import maps directly for the plugn to use to apply.
 
-| option  | default        | type     | required | details                                                     |
-| ------- | -------------- | -------- | -------- | ----------------------------------------------------------- |
-| path    | `cwd/eik.json` | `string` | `false`  | Path to eik.json file.                                      |
-| urls    | `[]`           | `array`  | `false`  | Array of import map URLs to fetch from.                     |
-| maps    | `[]`           | `array`  | `false`  | Array of import map as objects.                             |
+| option | default        | type     | required | details                                 |
+| ------ | -------------- | -------- | -------- | --------------------------------------- |
+| path   | `cwd/eik.json` | `string` | `false`  | Path to eik.json file.                  |
+| urls   | `[]`           | `array`  | `false`  | Array of import map URLs to fetch from. |
+| maps   | `[]`           | `array`  | `false`  | Array of import map as objects.         |
 
 The plugin will attempt to read a `eik.json` from the current working directory of the Node.js process.
 
@@ -69,7 +64,7 @@ The path to the location of an `eik.json` file can be specified with the `path`
 
 ```js
 await eik.load({
-    path: '/path/to/eik.json',
+	path: "/path/to/eik.json",
 });
 ```
 
@@ -77,7 +72,7 @@ The plugin can also load import maps directly from one or multiple URLs using th
 
 ```js
 await eik.load({
-    urls: ['http://myserver/import-maps/map.json'],
+	urls: ["http://myserver/import-maps/map.json"],
 });
 ```
 
@@ -85,11 +80,13 @@ Additionally, individual import maps can be specified using the `maps` option.
 
 ```js
 await eik.load({
-    maps: [{
-        imports: {
-            'lit-element': 'https://cdn.eik.dev/lit-element/v2',
-        }
-    }],
+	maps: [
+		{
+			imports: {
+				"lit-element": "https://cdn.eik.dev/lit-element/v2",
+			},
+		},
+	],
 });
 ```
 
@@ -99,13 +96,15 @@ ie. in the following example
 
 ```js
 await eik.load({
-    path: '/path/to/eik.json',
-    urls: ['http://myserver/import-maps/map.json'],
-    maps: [{
-        imports: {
-            'lit-element': 'https://cdn.eik.dev/lit-element/v2',
-        }
-    }],
+	path: "/path/to/eik.json",
+	urls: ["http://myserver/import-maps/map.json"],
+	maps: [
+		{
+			imports: {
+				"lit-element": "https://cdn.eik.dev/lit-element/v2",
+			},
+		},
+	],
 });
 ```
 
@@ -113,48 +112,28 @@ Any import map URLs in `eik.json` will be loaded first, then merged with (and ov
 
 ### .plugin()
 
-Returns the plugin which will apply the loaded import maps during build. The returned plugin should be appended to the ESBuild plugin array.
+Returns the plugin which will apply the loaded import maps during build. The returned plugin should be appended to the esbuild plugin array.
 
 ```js
-import * as eik from '@eik/esbuild-plugin';
-import esbuild from 'esbuild';
+import * as eik from "@eik/esbuild-plugin";
+import esbuild from "esbuild";
 
 await eik.load();
 
-esbuild.build({
-    entryPoints: ['src/main.js'],
-    bundle: true,
-    format: 'esm',
-    minify: false,
-    sourcemap: false,
-    target: ['chrome58', 'firefox57', 'safari11', 'edge16'],
-    plugins: [eik.plugin()],
-    outfile: 'out.js',
-}).catch(() => process.exit(1))
+esbuild
+	.build({
+		entryPoints: ["src/main.js"],
+		bundle: true,
+		format: "esm",
+		minify: false,
+		sourcemap: false,
+		target: ["es2017"],
+		plugins: [eik.plugin()],
+		outfile: "out.js",
+	})
+	.catch(() => process.exit(1));
 ```
 
 ### .clear()
 
-Clears the loaded import maps from the plugins internal cache. 
-
-## License
-
-Copyright (c) 2020 Finn.no
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Clears the loaded import maps from the plugins internal cache.

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@eik/esbuild-plugin",
-  "version": "2.0.0-next.1",
-  "description": "ESBuild plugin for loading import maps from a Eik server and applying the mapping to ECMAScript modules in preparation for upload to the same server.",
+  "version": "2.0.0",
+  "description": "esbuild plugin for loading import maps from a Eik server and applying the mapping to ECMAScript modules in preparation for upload to the same server.",
   "type": "module",
   "main": "./src/plugin.js",
+  "types": "./types/plugin.d.ts",
   "files": [
-    "src"
+    "src",
+    "types"
   ],
   "scripts": {
-    "test": "tap --no-coverage",
-    "test:snapshot": "TAP_SNAPSHOT=1 tap test/*.js --no-coverage",
-    "lint": "eslint . --ext=js",
-    "lint:fix": "eslint . --fix --ext=js"
+    "clean": "rimraf .tap node_modules types",
+    "test": "tap --disable-coverage --allow-empty-coverage",
+    "lint": "eslint .",
+    "lint:fix": "npm run lint -- --fix",
+    "types": "run-s types:module types:test",
+    "types:module": "tsc",
+    "types:test": "tsc --project tsconfig.test.json"
   },
   "repository": {
     "type": "git",
@@ -35,19 +40,26 @@
   },
   "homepage": "https://github.com/eik-lib/esbuild-plugin#readme",
   "devDependencies": {
-    "@semantic-release/changelog": "6.0.1",
-    "@semantic-release/git": "10.0.1",
-    "esbuild": "0.14.43",
-    "eslint": "8.16.0",
-    "eslint-config-airbnb-base": "15.0.0",
-    "eslint-plugin-import": "2.26.0",
-    "fastify": "3.29.0",
-    "semantic-release": "19.0.2",
-    "tap": "16.2.0"
+    "@eik/eslint-config": "1.0.13",
+    "@eik/prettier-config": "1.0.1",
+    "@eik/semantic-release-config": "1.0.2",
+    "@eik/typescript-config": "1.0.0",
+    "@types/esbuild-plugin-import-map": "0.0.3",
+    "esbuild": "0.25.3",
+    "eslint": "9.16.0",
+    "fastify": "4.28.1",
+    "npm-run-all2": "5.0.2",
+    "prettier": "3.4.1",
+    "rimraf": "6.0.1",
+    "semantic-release": "24.2.3",
+    "tap": "20.0.3",
+    "typescript": "5.7.2"
   },
   "dependencies": {
-    "@eik/common": "3.0.1",
-    "esbuild-plugin-import-map": "3.0.0-next.1",
-    "undici": "5.5.1"
+    "@eik/common": "5.1.0",
+    "esbuild-plugin-import-map": "2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/src/plugin.js

@@ -1,56 +1,83 @@
-/* eslint-disable no-restricted-syntax */
-
-import * as importMapPlugin from 'esbuild-plugin-import-map';
-import { helpers } from '@eik/common';
-import { request } from 'undici';
-
-const fetchImportMaps = async (urls = []) => {
-    try {
-        const maps = urls.map(async (map) => {
-            const {
-                statusCode,
-                body,
-            } = await request(map, { maxRedirections: 2 });
-
-            if (statusCode === 404) {
-                throw new Error('Import map could not be found on server');
-            } else if (statusCode >= 400 && statusCode < 500) {
-                throw new Error('Server rejected client request');
-            } else if (statusCode >= 500) {
-                throw new Error('Server error');
-            }
-            return body.json();
-        });
-        return await Promise.all(maps);
-    } catch (err) {
-        throw new Error(
-            `Unable to load import map file from server: ${err.message}`,
-        );
-    }
-};
+import * as importMapPlugin from "esbuild-plugin-import-map";
+import { helpers } from "@eik/common";
 
+/**
+ * @typedef {object} ImportMap
+ * @property {Record<string, string>} imports
+ */
+
+/**
+ * @typedef {object} LoadOptions
+ * @property {string} [path=process.cwd()]
+ * @property {string[]} [urls=[]] URLs to import maps hosted on an Eik server. Takes precedence over `eik.json`.
+ * @property {ImportMap[]} [maps=[]] Inline import maps that should be used. Takes precedence over `urls` and `eik.json`.
+ */
+
+/**
+ * Loads an Eik configuration or import maps directly for the plugn to use.
+ * Call before building.
+ *
+ * @param {LoadOptions} options
+ * @returns {Promise<void>}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
 export async function load({
-    path = process.cwd(),
-    maps = [],
-    urls = [],
+	path = process.cwd(),
+	maps = [],
+	urls = [],
 } = {}) {
-    const pMaps = Array.isArray(maps) ? maps : [maps];
-    const pUrls = Array.isArray(urls) ? urls : [urls];
+	const pMaps = Array.isArray(maps) ? maps : [maps];
+	const pUrls = Array.isArray(urls) ? urls : [urls];
 
-    const config = await helpers.getDefaults(path);
+	const config = helpers.getDefaults(path);
 
-    const fetched = await fetchImportMaps([...config.map, ...pUrls]);
-    const mappings = pMaps.concat(fetched);
+	const fetched = await helpers.fetchImportMaps([...config.map, ...pUrls]);
+	const mappings = fetched.concat(pMaps);
 
-    await importMapPlugin.load(mappings);
+	await importMapPlugin.load(mappings);
 }
 
+/**
+ * Clear the loaded import maps from the plugins internal cache.
+ *
+ * @returns {void}
+ */
 export function clear() {
-    importMapPlugin.clear();
+	importMapPlugin.clear();
 }
 
+/**
+ * @typedef {object} Plugin
+ * @property {string} name
+ * @property {(build: any) => void} setup
+ */
+
+/**
+ * Returns the plugin which will apply the loaded import maps during build.
+ *
+ * @returns {Plugin}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
 export function plugin() {
-    const obj = importMapPlugin.plugin();
-    obj.name = '@eik/esbuild-plugin';
-    return obj;
+	const obj = importMapPlugin.plugin();
+	obj.name = "@eik/esbuild-plugin";
+	return obj;
 }

package/types/plugin.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @typedef {object} ImportMap
+ * @property {Record<string, string>} imports
+ */
+/**
+ * @typedef {object} LoadOptions
+ * @property {string} [path=process.cwd()]
+ * @property {string[]} [urls=[]] URLs to import maps hosted on an Eik server. Takes precedence over `eik.json`.
+ * @property {ImportMap[]} [maps=[]] Inline import maps that should be used. Takes precedence over `urls` and `eik.json`.
+ */
+/**
+ * Loads an Eik configuration or import maps directly for the plugn to use.
+ * Call before building.
+ *
+ * @param {LoadOptions} options
+ * @returns {Promise<void>}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
+export function load({ path, maps, urls, }?: LoadOptions): Promise<void>;
+/**
+ * Clear the loaded import maps from the plugins internal cache.
+ *
+ * @returns {void}
+ */
+export function clear(): void;
+/**
+ * @typedef {object} Plugin
+ * @property {string} name
+ * @property {(build: any) => void} setup
+ */
+/**
+ * Returns the plugin which will apply the loaded import maps during build.
+ *
+ * @returns {Plugin}
+ * @example
+ * ```js
+ * import * as eik from "@eik/esbuild-plugin";
+ * import esbuild from "esbuild";
+ *
+ * await eik.load();
+ * await esbuild.build({
+ *   plugins: [eik.plugin()],
+ * });
+ * ```
+ */
+export function plugin(): Plugin;
+export type ImportMap = {
+    imports: Record<string, string>;
+};
+export type LoadOptions = {
+    path?: string;
+    /**
+     * URLs to import maps hosted on an Eik server. Takes precedence over `eik.json`.
+     */
+    urls?: string[];
+    /**
+     * Inline import maps that should be used. Takes precedence over `urls` and `eik.json`.
+     */
+    maps?: ImportMap[];
+};
+export type Plugin = {
+    name: string;
+    setup: (build: any) => void;
+};