esm-utils

Utilities you'll need when migrating to ESModule.

Install

yarn add esm-utils

Usage

import createEsmUtils from 'esm-utils'

const {
  dirname,
  filename,
  require,
  importModule,
  resolve,
  readJson,
  readJsonSync,
} = createEsmUtils(import.meta)

/* Those named exports only accept absolute path or URL */
import {
  importModule,
  readJson,
  loadJson,
  readJsonSync,
  loadJsonSync,
} from 'esm-utils'

API

`createEsmUtils(import.meta | URL | 'string')`

Returns an object with the following properties:

dirname (alias __dirname)
filename (alias __filename)
require
importModule (alias import)
resolve
readJson (alias loadJson)
readJsonSync (alias loadJsonSync)

Please read this note before you use dirname and filename

Sync version of readJson.

`utils.importModule(string | URL, options?)`

Same as import(), but accepts absolute path (on Windows, import('C:\\foo.js') error throws when pass a absolute path starts with a drive letter).

`options.traceSyntaxError`

type: boolean
default: false

Due to this Node.js issue, Node.js does not emit the location of the syntax error in the error thrown in dynamic import().

When set traceSyntaxError: true, we'll try to get a better error message by running node <file> in a child process.

`utils.readJson(string | URL)`

Returns Promise<jsonObject>.

`utils.readJsonSync(string | URL)`

Sync version of utils.readJson

`utils.resolve(string | URL)`

Ponyfill for import.meta.resolve.

If import.meta.resolve exits, use it directly, otherwise returns a simple wrapper of import-meta-resolve.

Import json file

With Import Assertions

import foo from './foo.json' assert {type: 'json'}

await import('./foo.json', {assert: {type: 'json'}})

With require, like CommonJS

import createEsmUtils from 'esm-utils'

const {require} = createEsmUtils(import.meta)
const foo = require('./foo.json')

With readJson or readJsonSync

import createEsmUtils from 'esm-utils'

const {readJson} = createEsmUtils(import.meta)
const foo = await readJson('./foo.json')

import createEsmUtils from 'esm-utils'

const {readJsonSync} = createEsmUtils(import.meta)
const foo = readJsonSync('./foo.json')

`importModule()`

Same as utils.importModule(), but only accept absolute path or URL.

`readJson()` (alias `loadJson`)

Same as utils.readJson(), but only accept absolute path or URL.

`readJsonSync()` (alias `loadJsonSync`)

Same as utils.readJsonSync(), but only accept absolute path or URL.

You don't need `dirname` and `filename`

The dirname and filename supposed to be a quick solution when migrating to ES Modules. In most cases, you don't need them, because many APIs accept URL directly.

/* BAD */
import fs from 'node:fs/promises'
import path from 'node:path'
import createEsmUtils from 'esm-utils'

const {dirname} = createEsmUtils(import.meta)
const buffer = await fs.readFile(
  path.join(dirname, './path/to/file')
)

/* GOOD */
import fs from 'node:fs/promises'

const buffer = await fs.readFile(
  new URL('./path/to/file', import.meta.url)
)

Current Tags

4.3.0 ... latest (2 years ago)

esm-utils

Install

Usage

API

createEsmUtils(import.meta | URL | 'string')

utils.importModule(string | URL, options?)

options.traceSyntaxError

utils.readJson(string | URL)

utils.readJsonSync(string | URL)

utils.resolve(string | URL)