esm-utils

Utilities you'll need when migrating to ESModule.

Install

1yarn add esm-utils

Usage

1import createEsmUtils from 'esm-utils'
2
3const {
4  dirname,
5  filename,
6  require,
7  importModule,
8  resolve,
9  readJson,
10  readJsonSync,
11} = createEsmUtils(import.meta)

1/* Those named exports only accept absolute path or URL */
2import {
3  importModule,
4  readJson,
5  loadJson,
6  readJsonSync,
7  loadJsonSync,
8} 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

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

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

With require, like CommonJS

1import createEsmUtils from 'esm-utils'
2
3const {require} = createEsmUtils(import.meta)
4const foo = require('./foo.json')

With readJson or readJsonSync

1import createEsmUtils from 'esm-utils'
2
3const {readJson} = createEsmUtils(import.meta)
4const foo = await readJson('./foo.json')

1import createEsmUtils from 'esm-utils'
2
3const {readJsonSync} = createEsmUtils(import.meta)
4const 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.

1/* BAD */
2import fs from 'node:fs/promises'
3import path from 'node:path'
4import createEsmUtils from 'esm-utils'
5
6const {dirname} = createEsmUtils(import.meta)
7const buffer = await fs.readFile(
8  path.join(dirname, './path/to/file')
9)

1/* GOOD */
2import fs from 'node:fs/promises'
3
4const buffer = await fs.readFile(
5  new URL('./path/to/file', import.meta.url)
6)