https://github.com/eik-lib/esbuild-plugin
esbuild plugin to do build-time import mapping using Eik
https://github.com/eik-lib/esbuild-plugin
eik eik-import-mapping esbuild esbuild-plugin
Last synced: about 2 months ago
JSON representation
esbuild plugin to do build-time import mapping using Eik
- Host: GitHub
- URL: https://github.com/eik-lib/esbuild-plugin
- Owner: eik-lib
- License: mit
- Created: 2020-11-20T20:42:06.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-14T20:17:04.000Z (8 months ago)
- Last Synced: 2024-10-30T17:44:09.084Z (7 months ago)
- Topics: eik, eik-import-mapping, esbuild, esbuild-plugin
- Language: JavaScript
- Homepage: https://eik.dev
- Size: 138 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @eik/esbuild-plugin
[esbuild](https://esbuild.github.io/) plugin for [build-time import mapping with Eik](https://eik.dev/docs/guides/esbuild).
## Installation
```bash
npm install --save-dev esbuild @eik/esbuild-plugin
```
## Usage
```js
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,
});
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
This module has the following API:
### .load(options)
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. |
The plugin will attempt to read a `eik.json` from the current working directory of the Node.js process.
```js
await eik.load();
```
The path to the location of an `eik.json` file can be specified with the `path` option.
```js
await eik.load({
path: "/path/to/eik.json",
});
```
The plugin can also load import maps directly from one or multiple URLs using the `urls` option.
```js
await eik.load({
urls: ["http://myserver/import-maps/map.json"],
});
```
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",
},
},
],
});
```
If several of these options are used, `maps` takes precedence over `urls` which takes precedence over values loaded from an `eik.json` file.
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",
},
},
],
});
```
Any import map URLs in `eik.json` will be loaded first, then merged with (and overridden if necessary by) the result of fetching from `http://myserver/import-map` before finally being merged with (and overriden if necessary by) specific mappings defined in `maps`. (In this case `lit-element`)
### .plugin()
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";
await eik.load();
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.