Dynamic import() with "module": "commonjs"

[cspotcode]

With "module": "commonjs", TypeScript will transform dynamic import() calls into require() calls. But sometimes, you actually want to use node's dynamic await import() from within a CommonJS module to asynchronously load a native ESM module.

Here are a few options to do that:

Option one: use tsimportlib

This has been published as a library: tsimportlib

Note the caveats "Limitations" in the README.

npm install tsimportlib

import {dynamicImport} from 'tsimportlib';

async function main() {
    const dynamicallyImportedEsmModule = await dynamicImport('truly-esm-module', module) as typeof import('truly-esm-module');
}

Option two: copy-paste this helper function

Copy-paste the code from tsimportlib into your project: https://unpkg.com/[email protected]/index.js

Put this in a file that is not transformed by ts-node / typescript. Typically, this can be a .cjs file, but keep in mind that with allowJs turned on, ts-node may transform non-ts files.

// import-esm.cjs
const Module = require('module');
const {isAbsolute} = require('path');
async function importEsm(specifier, module) {
    if(isAbsolute) {
        return import(specifier);
    }
    let resolvedPath;
    try {
        const req = Module.createRequire(module.filename);
        try {
            resolvedPath = req.resolve(Path.posix.join(specifier, 'package.json'));
        } catch {
            resolvedPath = req.resolve(specifier);
        }
    } catch {
        throw new Error(`Unable to locate module "${specifier}" relative to "${module?.filename}" using the CommonJS resolver.  Consider passing an absolute path to the target module.`);
    }
    return import(resolvedPath);
}

Then use it like this:

import {importEsm} from './import-esm';
const dynamicallyLoadedEsmModule = await importEsm('./other/module', module);

Essentially, we must place the import() in a file that does not get compiled so that the import() remains intact. We must manually resolve the import relative to the calling module in case they are in different directories, or else relative imports will break.

Option three: --experimental-import-meta-resolve

Note: I have not tested this option. If you do, let us know!

If you are willing and able to install node's --experimental-import-meta-resolve then you may be able to use a shorter and more correct helper function:

// import-esm.cjs
exports.importEsm = async function(specifier, module) {
    return (await import('./import-esm-internal.mjs')).importEsm(specifier, module);
}

// import-esm-internal.mjs
export function importEsm(specifier, module) {
    return import(import.meta.resolve(specifier, module.filename));
}

Option four: new Function

Alternatively, you can create a dynamic importer inline with new Function to prevent the typescript compiler from touching it. This does not require any extra files, but you must ensure you understand how to do this safely, and your linter may forbid it.

const dynamicImport = new Function('specifier', 'return import(specifier)');
const dynamicallyLoadedEsmModule = await dynamicImport('./other/module');

[cspotcode]

This is a recipe for solving a common problem. We'll try to keep it up-to-date. If it is confusing, we can update it based on questions posted here.

[gentunian]

what about typings? I came across this issue while trying to use an ESM module with typings defined but when using option FOUR the imported function doesn't have a type.

[realityking]

This might be due to my inexperience with Typescript but this seems to be the challenge:

Essentially, we must place the import() in a file that does not get compiled so that the import() remains intact.

I couldn't figure out a way to force Typescript not to compile a file that is included by a TS file. Even if it's a .js (and not a .ts) file, the import call will be rewritten.

[realityking]

To elaborate on this more, here's what I've tried

tsconfig.json:

{
  "tsNode": {
    "ignore": ["/node_modules/", "/spec/import-esm.js"]
  }
}

spec/import-esm.js

function importESM(file) {
    return import(file);
}

module.exports = importESM;

spec/test.ts

const importESM = require('./import-esm.js')

console.log({importESM: importESM.toString()})

The output looks like this:

{
  importESM: 'function importESM(file) {\n' +
    '    return Promise.resolve().then(() => require(file));\n' +
    '}'
}

So Typescript is still rewriting the import to a require.

[cspotcode]

We transform .js files when allowJs is enabled, so I would check that you are absolutely certain if ts-node is loading the config you expect or if it is loading a config you do not expect, and if that config is correct or has options you did not realize were there.

[stevemarksd]

Code seems invalid:

TS1005: ',' expected.. I never saw this syntax either: const {importEsm} from './import-esm.js';, is not import?

Changed to const {importEsm} = require( './import-esm.js');,

but getting:

return import(import.meta.resolve(specifier, module.filename));
                       ^^^^

SyntaxError: Cannot use 'import.meta' outside a module

Added "type": "module", to package.json and getting:

ReferenceError: exports is not defined in ES module scope

Changed to "type": "commonjs", and back to:

 return import(import.meta.resolve(specifier, module.filename));
                       ^^^^

SyntaxError: Cannot use 'import.meta' outside a module

Note: tsconfig:

  "ignore": ["./server/import-esm.js"]

---

Trial #2

Changed to

exports.importEsm = function(file) {
  return import(file);
}

can't find the file now. Enabled js in tsconfig:

error - unhandledRejection: Error [ERR_REQUIRE_ESM]: require() of ES Module \node_modules\favicons\dist\index.js from \server\import-esm.js not supported.
Instead change the require of index.js in \server\import-esm.js to a dynamic import() which is available in all CommonJS modules.

Back to square 1. - This is where I started.

---

I guess this can't be used anymore. It's really insane how hard it to use ESM module with ts-node. Wasted hours trying random stuff... and still can't find a solution.

[stevemarksd]

I didn't try, I was try to avoid adding new libs. But I might try as production build stops working once the .js file is required.. such a nightmare ://

[stevemarksd]

So basically the .js file is not being copied to the dist. I need to do this:

  "include": ["server/**/*.ts", "server/utils/tsimportlib/index.js"]

But importing it this way, it breaks with Error [ERR_REQUIRE_ESM]: require() of ES Module

If I set:

    "allowJs": false

it will not emit the js file at all. The ts docs are kind of poor as it doesn't mention these "features" (cough bugs).

With ts-node the above works, but once you compile to js and run with node, it breaks as the file is not found. Or if we enable allowJs, then the file is processed by tsc and loses the import.

[stevemarksd]

the file server/utils/tsimportlib/index.js is emitted as: (which is not going to import the esm module)

At this point is faster to fork the repo, compile to js and publish to npm..

"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    var desc = Object.getOwnPropertyDescriptor(m, k);
    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
      desc = { enumerable: true, get: function() { return m[k]; } };
    }
    Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
    Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
    o["default"] = v;
});
var __importStar = (this && this.__importStar) || function (mod) {
    if (mod && mod.__esModule) return mod;
    var result = {};
    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
    __setModuleDefault(result, mod);
    return result;
};
const Module = require('module');
const { isAbsolute } = require('path');
exports.dynamicImport = importEsm;
exports.importEsm = importEsm;
async function importEsm(specifier, module) {
    if (isAbsolute) {
        return Promise.resolve().then(() => __importStar(require(specifier)));
    }
    let resolvedPath;
    try {
        const req = Module.createRequire(module.filename);
        try {
            resolvedPath = req.resolve(Path.posix.join(specifier, 'package.json'));
        }
        catch {
            resolvedPath = req.resolve(specifier);
        }
    }
    catch {
        throw new Error(`Unable to locate module "${specifier}" relative to "${module?.filename}" using the CommonJS resolver.  Consider passing an absolute path to the target module.`);
    }
    return Promise.resolve().then(() => __importStar(require(resolvedPath)));
}

[stevemarksd]

Created an es5 version with ts bundled. https://www.npmjs.com/package/@esm-to-es5/favicons works out of the box with everything :)

[cspotcode]

Copying tsimportlib into your project is a deliberately non-standard approach and will make your life more difficult, as you experienced. Something more standard like npm install tsimportlib is better.

[stevemarksd]

with my own package I can just import types and real fn in a cleaner way:

import favicons, {FaviconResponse} from '@esm-to-es5/favicons';

The benefit of esm is minimal, but having to change ton of stuff is too expensive. I rather drop the library or re-implement myself at this point.

[Rush]

What if I do want ts-node to compile the dynamic ESM module and yet keep the ordinary files as common.js?

[MondoGao]

Use moduleResolution: 'node16' with module: 'commonjs' in tsconfig.json, ts will keep all the dynamic import statements as is.

But ts-node will panic at this situation.

[romatou]

Doesn't like the directory import (without extension). Any thoughts on fixing this? Prefer not to write them.

[romatou]

Option four: new Function

const dynamicImport = new Function('specifier', 'return import(specifier)');
const dynamicallyLoadedEsmModule = await dynamicImport('./other/module');

This one helped me fix my problem in a case where external packages in a project are limited. Thanks a lot 👍

[Maxim-Mazurok]

Note for "Option two: copy-paste this helper function" that on Windows we need to use import(pathToFileURL(resolvedPath).href) as per https://github.com/cspotcode/tsimportlib/pull/7/files

[gentunian]

Ok, I came across this approach for resolving typings.

My dynamic import:

import { basename } from 'path';
const defaultOrName = (path: string) => path.endsWith('index.js') ? 'default' : basename(path).replace('.js', '');

// we use this to import magidoc module because it's an ESM module and direct
// imports won't work...
// see: https://github.com/TypeStrong/ts-node/discussions/1290
const _import = async (path: string) => new Function('specifier', 'return import(specifier)')(path);

// we create a wrapper for the _import above and returns the `default` exported method/function/symbol
// inferred by the module name or a custom one base on user preferences...
export const dynamicImport = async <T>(path: string, symbol?: string) => (await _import(path))[symbol ?? defaultOrName(path)] as T;

Then, I import/re-export types like the following -- in my case, I'm trying to import magidoc ESM into a commonjs app --:

// imports
import type { default as generate } from '@magidoc/cli/build/commands/generate/index';
import type { withStacktrace } from '@magidoc/cli/build/commands/utils/withStacktrace';
import type { readConfiguration } from '@magidoc/cli/build/config/reader';
import type { MagidocConfiguration } from '@magidoc/cli/build/config/types';
// exports
export type { MagidocConfiguration };
export type { GenerationConfig } from '@magidoc/cli/build/commands/generate/index';
export type GenerateFunction = typeof generate;
export type withStacktraceFunction = typeof withStacktrace;
export type readConfigurationFunction = typeof readConfiguration;
export type GenerateWrapper = (config: MagidocConfiguration) => Promise<void>;

And then I use it like:

const readConfiguration = await dynamicImport<readConfigurationFunction>('@magidoc/cli/build/config/reader.js', 'readConfiguration');
const withStacktrace = await dynamicImport<withStacktraceFunction>('@magidoc/cli/build/commands/utils/withStacktrace.js')
const generate = await dynamicImport<GenerateFunction>('@magidoc/cli/build/commands/generate/index.js')

This allows me to have typings while coding and it also works.

[sacru2red]

Can use jiti instead of tsimportlib. (Weekly Downloads: 12M)

[JUSTICEESSIELP]

How do I use all what you guys are saying with my tsconfig and package .json so I deploy the code to docker but first I want to npm run build for it not to have problems

this was currently what I got

\dist\cjs\config\utils\cookies.js not supported.
Instead change the require of index.js in

\dist\cjs\config\utils\cookies.js to a dynamic import() which is available in all CommonJS modules