search

sheerlox / import-from-esm

Almost drop-in "import-from" replacement that supports loading both ESM & CJS modules
MIT License
2 stars 2 forks source link
esm import module path resolve

readme

import-from-esm

Version Monthly Downloads Test CodeQL Coverage OpenSSF Scorecard

Overview

Import a module like with require() but from a given path (for ESM)

This library intends to be an almost drop-in replacement of import-from (from which it is forked), exposing the same API and behavior but also supporting ES modules (ESM). Just add await before importFrom/importFrom.silent

Motivation

The main benefit of using import-from is that it abstracts the need to resolve the path and create a require statement. Its code is really straightforward:

(fromDirectory, moduleId) => createRequire(path.resolve(fromDirectory, "noop.js"))(moduleId);

In the case of import-from-esm, there are a few additional benefits because of the way ESM works:

  1. Importing a package installed along a library (in the parent application) from that library is no longer possible (which was the issue that made me work on this library). You need to use import.meta.resolve, which is behind an experimental flag (although there's a ponyfill available at wooorm/import-meta-resolve, which import-from-esm uses under-the-hood).
  2. If the file you're trying to import (whether relative, package, export map, etc ...) is a JSON file, you need to detect that and use import assertions or require (while the former is still in experimental).
  3. File extensions are now mandatory for relative paths. import-from-esm re-introduces require's file extension discovery.

As you can see, there is quite a bit of complexity that is abstracted behind import-from-esm. The first bullet point issue affected both @semantic-release/commit-analyzer and @semantic-release/release-notes-generator. After spending hours on research to solve the issue, I realized that the work I was doing would benefit others as well, so I decided to create a package out of it.

As a proponent of ESM, I have put a lot of thought into poly-filling require features for import, but finally came to the conclusion that developing a package to facilitate the ecosystem transition to ESM by reducing friction was a good thing.

Install

$ npm install import-from-esm

Usage

import importFrom from "import-from-esm";

// there is a file at `./foo/bar.{js,mjs,cjs,json}`

await importFrom("foo", "./bar");

API

importFrom(fromDirectory, moduleId)

Like require(), throws when the module can't be found.

importFrom.silent(fromDirectory, moduleId)

Returns undefined instead of throwing when the module can't be found.

fromDirectory

Type: string

Directory to import from.

moduleId

Type: string

What you would use in require().

Tip

Create a partial using a bound function if you want to import from the same fromDir multiple times:

const importFromFoo = importFrom.bind(null, "foo");

importFromFoo("./bar");
importFromFoo("./baz");