Skip to content
This repository has been archived by the owner on Aug 22, 2024. It is now read-only.

⛔️ [DEPRECATED] A tiny wrapper around the dynamic import function for "requiring" ES modules in CJS code bundled by Webpack without triggering the ugly "critical dependency" warning

License

Notifications You must be signed in to change notification settings

Xunnamius/import-esm-interop

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Black Lives Matter! !!UNMAINTAINED!!

⛔️ DEPRECATED/UNMAINTAINED

Caution

With much improved ESM-CJS interop support compared to several years ago, as well as improvements to babel and webpack, the major use cases (and major blockers) for this package have thankfully been fixed. Yay! No need to bother with any of the below.

This package exposes a tiny Node.js-only wrapper around the import function. This purpose of this wrapper is as syntactic sugar for dynamic imports of externalized ESM dependencies in TypeScript/ESM source destined to be bundled as CJS by Webpack. Since this package should itself be an externalized dependency, using import-esm-interop ensures:

Hence, this package has a very niche use case and you probably don't need it. For most packages, it's easier to use their CJS entry point if available. In a decade (🤞🏿) when CJS is dead and buried and ESM reigns supreme, this package will be deprecated.

This package also passes through TypeScript typings if provided.

Install

npm install import-esm-interop

Usage

This interop function should only be used in CJS code or code that is compiled down to CJS (such as TypeScript)!

const { importEsm } = require('import-esm-interop');

// Equivalent to (await import('some-lib')).default
const someLib = await importEsm('some-lib');

// Equivalent to the above
const someLib = await importEsm('some-lib', 'default');

// Equivalent to the above, but with TypeScript typings
const someLib = await importEsm<import('some-lib').default>('some-lib');

// Equivalent to (await import('some-lib')).aNamedExport
const aNamedExport = await importEsm('some-lib', 'aNamedExport');

// Equivalent to { bNamedExport: (...).bNamedExport, cNamedExport: ... }
const { bNamedExport, cNamedExport } = await importEsm(
  'some-lib',
  'bNamedExport',
  'cNamedExport'
);

// Equivalent to the above, but with TypeScript typings
const { bNamedExport, cNamedExport } = await importEsm<{
  bNamedExport: import('some-lib').bNamedExport,
  cNamedExport: import('some-lib').cNamedExport
}>('some-lib', 'bNamedExport', 'cNamedExport');

// Equivalent to await import('some-lib')
const SomeLib = await importEsm('some-lib', '*');

// Equivalent to the above, but with TypeScript typings
const SomeLib = await importEsm<import('some-lib')>('some-lib', '*');

If reusing the same typed import multiple times, you can make things less painful by extracting away the dynamic import into a top-level function. Said function could even be placed in a shared util file somewhere.

For example:

// file: ./vendor-interop.ts

export const importSomeLib = async () => {
  return importEsm('some-lib', 'bNamedExport', 'cNamedExport') as {
    bNamedExport: import('some-lib').bNamedExport,
    cNamedExport: import('some-lib').cNamedExport
  };
}

// file: ./index.ts

import { importSomeLib } from './vendor-interop'

export async function doesSomething() {
  const { bNamedExport } = await importSomeLib();
  bNamedExport();
}

Again, we use importEsm instead of inlining the dynamic import to avoid problems with Webpack. If you're not bundling your source, then there is no need to use this sugar function!

Documentation

Further documentation can be found under docs/.

This is a CJS2 package built for Node14 and above. Due to it being for CJS<->ESM interop, this package is only available via require(...) and cannot be imported by ESM code! Further, this package is not meant to be bundled (and will likely cause an error if it is attempted), and should instead be externalized along with every other module under node_modules/.

For TypeScript and IDEs, each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes an exports[ENTRY].types key pointing to its respective TypeScript declarations file. There may be other keys for other runtimes as well, including node and browser. Finally, package.json also includes the sideEffects key, which I set to false by default for most of my libraries.

License

FOSSA analysis

Contributing and Support

New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.

About

⛔️ [DEPRECATED] A tiny wrapper around the dynamic import function for "requiring" ES modules in CJS code bundled by Webpack without triggering the ugly "critical dependency" warning

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks