ESM loader that handles TypeScript path mapping

[geigerzaehler]

At the moment, the ESM loader does not handle TypeScript path mappings. To make it work you can use the following custom loader:

// `loader.js`
import {
  resolve as resolveTs,
  getFormat,
  transformSource,
} from "ts-node/esm";
import * as tsConfigPaths from "tsconfig-paths"

export { getFormat, transformSource };

const { absoluteBaseUrl, paths } = tsConfigPaths.loadConfig()
const matchPath = tsConfigPaths.createMatchPath(absoluteBaseUrl, paths)

export function resolve(specifier, context, defaultResolver) {
  const mappedSpecifier = matchPath(specifier)
  if (mappedSpecifier) {
    specifier = `${mappedSpecifier}.js`
  }
  return resolveTs(specifier, context, defaultResolver);
}

Then use the loader with node --loader loader.js my-script.ts.

Caveat: This only works for module specifiers without an extension. For example, import "/foo/bar" works, but import "/foo/bar.js" and import "/foo/bar.ts" do not.

[AgainPsychoX]

Under Windows, it the specifier also require file:// at the beginning. Without it, there is error:

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only file and data URLs are supported by the default ESM loader. On Windows, absolute paths must be valid file:// URLs. Received protocol 'd:'

on absolute paths generated by tsconfig-paths as for mapping.

[AgainPsychoX]

If anyone would be interested, I am using .ts files with imports ending with no extension, so in my case I use node --experimental-specifier-resolution=node --loader ./loader.js ./src/main.ts (and the file:// fix included).

[charles-allen]

I'm using this to get it working on Windows:

resolveTs(pathToFileURL(`${match}`).href, ctx, defaultResolve)

[unicornware]

awesome workaround! to get this working for me, i needed to account for directories as well:

/**
 * Custom resolver that handles TypeScript path mappings.
 *
 * @see https://github.com/TypeStrong/ts-node/discussions/1450
 * @see https://github.com/dividab/tsconfig-paths
 *
 * @async
 * @param {string} specifier - Name of file to resolve
 * @param {{ parentURL: string }} ctx - Resolver context
 * @param {typeof resolveTs} defaultResolve - Default resolver function
 * @return {Promise<{ url: string }>} Promise containing object with file path
 */
export const resolve = async (specifier, ctx, defaultResolve) => {
  // Get base URL and path aliases
  const { absoluteBaseUrl, paths } = loadConfig(process.cwd())

  // Attempt to resolve path based on path aliases
  const match = createMatchPath(absoluteBaseUrl, paths)(specifier)

  // Update specifier if match was found
  if (match) {
    try {
      const directory = lstatSync(match).isDirectory()
      specifier = `${match}${directory ? '/index.js' : '.js'}`
    } catch {
      specifier = `${match}.js`
    }
  }

  return resolveTs(specifier, ctx, defaultResolve)
}

for those interested, my custom loader:

import { lstatSync } from 'fs'
import path from 'path'
import { getFormat as getFormatTs, resolve as resolveTs } from 'ts-node/esm'
import { createMatchPath, loadConfig } from 'tsconfig-paths'
import useDualExports from '../helpers/use-dual-exports'

/**
 * @file Helpers - Custom ESM Loader
 * @module tools/loaders/esm
 * @see https://github.com/TypeStrong/ts-node/issues/1007
 */

/** @typedef {'builtin'|'commonjs'|'dynamic'|'json'|'module'|'wasm'} Format */

// ! Add ESM-compatible export statement to `exports.default` statements
// ! Fixes: `TypeError: logger is not a function`
useDualExports([`${process.env.NODE_MODULES}/@flex-development/grease/cjs/**`])

/**
 * ESM requires all imported files to have extensions. Unfortunately, most `bin`
 * scripts do **not** include extensions.
 *
 * This custom hook provides support for extensionless files by assuming they're
 * all `commonjs` modules.
 *
 * @see https://github.com/nodejs/node/pull/31415
 * @see https://github.com/nodejs/modules/issues/488#issuecomment-589274887
 * @see https://github.com/nodejs/modules/issues/488#issuecomment-804895142
 *
 * @async
 * @param {string} url - File URL
 * @param {{}} ctx - Resolver context
 * @param {typeof getFormatTs} defaultGetFormat - Default format function
 * @return {Promise<{ format: Format }>} Promise containing module format
 */
export const getFormat = async (url, ctx, defaultGetFormat) => {
  // Get file extension
  const ext = path.extname(url)

  // Support extensionless files in `bin` scripts
  if (/^file:\/\/\/.*\/bin\//.test(url) && !ext) return { format: 'commonjs' }

  // Load TypeScript files as ESM
  // See `tsconfig.json#ts-node.moduleTypes` for file-specific overrides
  if (ext === '.ts') return { format: 'module' }

  // Use default format module for all other files
  return defaultGetFormat(url, ctx, defaultGetFormat)
}

/**
 * Custom resolver that handles TypeScript path mappings.
 *
 * @see https://github.com/TypeStrong/ts-node/discussions/1450
 * @see https://github.com/dividab/tsconfig-paths
 *
 * @async
 * @param {string} specifier - Name of file to resolve
 * @param {{ parentURL: string }} ctx - Resolver context
 * @param {typeof resolveTs} defaultResolve - Default resolver function
 * @return {Promise<{ url: string }>} Promise containing object with file path
 */
export const resolve = async (specifier, ctx, defaultResolve) => {
  // Get base URL and path aliases
  const { absoluteBaseUrl, paths } = loadConfig(process.cwd())

  // Attempt to resolve path based on path aliases
  const match = createMatchPath(absoluteBaseUrl, paths)(specifier)

  // Update specifier if match was found
  if (match) {
    try {
      const directory = lstatSync(match).isDirectory()
      specifier = `${match}${directory ? '/index.js' : '.js'}`
    } catch {
      specifier = `${match}.js`
    }
  }

  return resolveTs(specifier, ctx, defaultResolve)
}

export { transformSource } from 'ts-node/esm'

example using custom loader: https://github.com/flex-development/log/tree/8bb4e104918bb0588d3aaa8aeb8733811bc1ac46

[unicornware]

once again, for those interested, my updated loader configuration 😅😊:

/**
 * @file Custom Loader Hooks
 * @module loader
 * @see https://nodejs.org/api/esm.html#loaders
 */

import * as mlly from '@flex-development/mlly'
import * as pathe from '@flex-development/pathe'
import * as tscu from '@flex-development/tsconfig-utils'
import * as tutils from '@flex-development/tutils'
import * as esbuild from 'esbuild'
import { fileURLToPath, pathToFileURL } from 'node:url'

// add support for extensionless files in "bin" scripts
// https://github.com/nodejs/modules/issues/488
mlly.EXTENSION_FORMAT_MAP.set('', mlly.Format.COMMONJS)

/**
 * URL of tsconfig file.
 *
 * @type {import('node:url').URL}
 * @const tsconfig
 */
const tsconfig = mlly.toURL('tsconfig.json')

/**
 * TypeScript compiler options.
 *
 * @type {tscu.CompilerOptions}
 * @const compilerOptions
 */
const compilerOptions = tscu.loadCompilerOptions(tsconfig)

/**
 * Determines how the module at the given `url` should be interpreted,
 * retrieved, and parsed.
 *
 * @see {@linkcode LoadHookContext}
 * @see https://nodejs.org/api/esm.html#loadurl-context-nextload
 *
 * @async
 *
 * @param {string} url - Resolved module URL
 * @param {LoadHookContext} context - Hook context
 * @return {Promise<LoadHookResult>} Hook result
 */
export const load = async (url, context) => {
  // get module format
  context.format = context.format ?? (await mlly.getFormat(url))

  // validate import assertions
  mlly.validateAssertions(url, context.format, context.importAssertions)

  /**
   * File extension of {@linkcode url}.
   *
   * @type {pathe.Ext | tutils.EmptyString}
   * @const ext
   */
  const ext = pathe.extname(url)

  /**
   * Source code.
   *
   * @type {Uint8Array | string | undefined}
   * @var source
   */
  let source = await mlly.getSource(url, { format: context.format })

  // transform typescript files
  if (/^\.(?:cts|mts|tsx?)$/.test(ext) && !/\.d\.(?:cts|mts|ts)$/.test(url)) {
    // push require condition for .cts files and update format
    if (ext === '.cts') {
      context.conditions = context.conditions ?? []
      context.conditions.unshift('require', 'node')
      context.format = mlly.Format.MODULE
    }

    // resolve path aliases
    source = await tscu.resolvePaths(source, {
      conditions: context.conditions,
      ext: '',
      parent: url,
      tsconfig
    })

    // resolve modules
    source = await mlly.resolveModules(source, {
      conditions: context.conditions,
      parent: url
    })

    // transpile source code
    const { code } = await esbuild.transform(source, {
      format: 'esm',
      loader: ext.slice(/^\.[cm]/.test(ext) ? 2 : 1),
      minify: false,
      sourcefile: fileURLToPath(url),
      sourcemap: 'inline',
      target: `node${process.versions.node}`,
      tsconfigRaw: { compilerOptions: tsconfig.compilerOptions }
    })

    // set source code to transpiled source
    source = code
  }

  return { format: context.format, shortCircuit: true, source }
}

/**
 * Resolves the given module `specifier`.
 *
 * Adds supports for:
 *
 * - Path alias resolution
 * - Extensionless file and directory index resolution
 *
 * @see {@linkcode ResolveHookContext}
 * @see https://nodejs.org/api/esm.html#resolvespecifier-context-nextresolve
 *
 * @async
 *
 * @param {string} specifier - Module specifier
 * @param {ResolveHookContext} context - Hook context
 * @return {Promise<ResolveHookResult>} Hook result
 * @throws {Error}
 */
export const resolve = async (specifier, context) => {
  const { conditions, parentURL: parent } = context

  // resolve path alias
  specifier = await mlly.resolveAlias(specifier, {
    aliases: tscu.loadPaths(tsconfig),
    conditions,
    cwd: pathToFileURL(compilerOptions.baseUrl),
    parent
  })

  /**
   * Resolved module URL.
   *
   * @type {import('node:url').URL}
   * @const url
   */
  const url = await mlly.resolveModule(specifier, {
    conditions,
    parent: parent?.startsWith('file:') ? parent : specifier
  })

  return {
    format: await mlly.getFormat(url),
    shortCircuit: true,
    url: url.href
  }
}

my tsconfig file and other relevant configs can be seen here

[arjunyel]

@unicornware hi friend, any chance you can publish your loader as an NPM package?

[unicornware]

@arjunyel definitely! i'll drop a link in a few days 😊

[arjunyel]

@unicornware I got it working using a different loader, sorry for the trouble! #1450 (comment)

[flazouh]

Hi, did you have problems with commonJS such as:

/opt/homebrew/bin/yarn run seed
(node:11327) ExperimentalWarning: Custom ESM Loaders is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
file:///Users/...src/utils/email-utils/utils.ts:1
import { convertFromRaw, convertToRaw, Modifier, SelectionState } from "file:///Users/.../backend/node_modules/draft-js/lib/Draft.js";
                                       ^^^^^^^^
SyntaxError: Named export 'Modifier' not found. The requested module 'file:///Users/.../backend/node_modules/draft-js/lib/Draft.js' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'file:///Users/.../backend/node_modules/draft-js/lib/Draft.js';
const { convertFromRaw, convertToRaw, Modifier, SelectionState } = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:190:5)

Node.js v18.17.1

Process finished with exit code 1

when doing TS_NODE_PROJECT=tsconfig.seed.json node --loader ./loader.js src/seed.ts

with

{
  "compilerOptions": {
    "baseUrl": "./",
    "target": "es5",
    "module": "ESNEXT",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "paths": {
      "@/*": [
        "src/*"
      ]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"]
}

Thanks in advance for your help

[Haprog]

These don't seem to work with new versions of Node 16 and 17 which have a new hooks API. Could somebody update these for the new API? Trying to use the above as is with Node 16.13.0 or 17.1.0 results in ERR_INVALID_MODULE_SPECIFIER

[unicornware]

do you have a snippet of the exact error? would be happy to help you debug, just finished a couple weeks worth of debugging / implementing fixes for a few of my projects 😅

[andyjy]

Fixed by adding the newly-added load to the exports passed through from ts-node/esm

Just change the last line to export { transformSource, load } from "ts-node/esm";

[charles-allen]

Firstly -- really appreciate this; it's unblocked me :)

I'm a bit confused by the file extensions... my app is ESM, so the imports all end in .js, and require explicit references to index.js. Local imports don't work without it.

With this loader, path-aliased imports that end with .js fail. Since I'm using ESM everywhere, I'm expecting to suffix .js everywhere (though I'd be equally happy to suffix nowhere; I suspect that's coming?!).

Working examples:

import { foo } from '@mypackage/utils/helpers/index'
import { foo } from '@mypackage/utils/helpers'
import { bar } from './helpers/index.js'

Broken examples:

import { foo } from '@mypackage/utils/helpers/index.js' // I'm expecting this to work
import { bar } from './helpers/index'
import { bar } from './helpers'

[charles-allen]

The best I found was to start Node with --experimental-specifier-resolution=node (which allows you to skip .js/index.js) -- though this only works if you're happy using that flag in production too:

"serve": "cross-env TS_NODE_PROJECT=\"tsconfig.build.json\" node --experimental-specifier-resolution=node --loader ./loader.js src/index.ts",

Then I'm using this implementation of loader.js, which works for me on both Windows & MacOS:

import { resolve as resolveTs } from 'ts-node/esm'
import * as tsConfigPaths from 'tsconfig-paths'
import { pathToFileURL } from 'url'

const { absoluteBaseUrl, paths } = tsConfigPaths.loadConfig()
const matchPath = tsConfigPaths.createMatchPath(absoluteBaseUrl, paths)

export function resolve (specifier, ctx, defaultResolve) {
  const match = matchPath(specifier)
  return match
    ? resolveTs(pathToFileURL(`${match}`).href, ctx, defaultResolve)
    : resolveTs(specifier, ctx, defaultResolve)
}

export { load, transformSource } from 'ts-node/esm'

If you want to continue suffixing .js/index.js for standard built ESM, then I found that I had to remove the extension before calling matchPath, and add it back before calling resolveTs... something like this:

const lastIndexOfIndex = specifier.lastIndexOf('/index.js')
if (lastIndexOfIndex !== -1) {
  // Handle index.js
  const trimmed = specifier.substring(0, lastIndexOfIndex)
  const match = matchPath(trimmed)
  if (match) return resolveTs(pathToFileURL(`${match}/index.js`).href, ctx, defaultResolve)
} else if (specifier.endsWith('.js')) {
  // Handle *.js
  const trimmed = specifier.substring(0, specifier.length - 3)
  const match = matchPath(trimmed)
  if (match) return resolveTs(pathToFileURL(`${match}.js`).href, ctx, defaultResolve)
}
return resolveTs(specifier, ctx, defaultResolve)

I've patched this together from several sources, so credit goes to the original authors:

• @geigerzaehler for loader approach & original script
• @andyjy for Node16+ update
• @jonerer for Windows support with pathToFileUrl
• @sodatea for avoiding file extensions

[BlackSwan2019]

For those having these issues working with WebdriverIO v8 (noted here) with TS aliases no longer working, for example this doesn't work anymore:

import { SomeScreen } from '@screens'

and I feared I'd have to change all imports to relative like:

import { SomeScreen } from '../../screens/index.ts'

I did these steps to get my aliases working again:

1. I copied the code from the workaround above (thanks charles-allen et al.) and made a file in my project called loader.js.

2. Additionally, right before the wdio CLI command is invoked, I also export TS_NODE_PROJECT=tsconfig.json.

3. Then, in the wdio config file, I set the execArgv field like so:
   execArgv: ['--experimental-specifier-resolution=node', '--loader', './loader.js'].

I ran some Appium tests and my @screen alias works again.

Note: For this solution, I still added tsconfig-paths to my project, but I never set it in the wdio config file, e.g., cucumberOpts.requireModule: ['tsconfig-paths/register']. Instead, tsconfig-paths gets used by loader.js.

[erwinheitzman]

Hi @BlackSwan2019 are you sure you were running this in a ESM project? We (the team behind WebdriverIO) have not been able to get it to work as of yet and I tried your solution without any success using node20, the latest versions of our packages and the project configured as ESM. Could you share a repo which shows this working?

[BlackSwan2019]

Hi @erwinheitzman. I believe we are configured fully for ESM. Our TS config is set to "ESNext" for both target and module. However, the moduleResolution is set for "Node".

We are using node18; can you try with that?

This is a corporate repo unfortunately, so I can't share it.

[erwinheitzman]

@BlackSwan2019 thank you for getting back to me, I can test using node 18 but I would like to ask you to let me know if you have a "type" property in your package.json that is set to "module". If not, you project is cjs and not esm

[BlackSwan2019]

@erwinheitzman Our package.json indeed has type set to "module". That was one of the things I had to add to get things working again.

[testgitdl]

Hello,

cannot get it to work. Would really appreciate your help.

So I have a test.ts which looks like this:
import { HelloWord } from 'e2e-api';
let myVar;
console.log('aaaaaa');
myVar = new HelloWord('Emma');
myVar.setText();

and in this test.ts I'm importing e2e-api from my dist folder.
I get an error: "CustomError: Cannot find package 'e2e-api' imported from D:\myproj\tests\test.ts"

**I tried the following:

• node --experimental-specifier-resolution=node --loader ./loader.js .\tests\test.ts
• node --loader ts-node/esm -r tsconfig-paths/register .\tests\test.ts**

Both cases I get the same error mentioned above.
If I do an npm pack and then install the e2e-api package (so I have it in node_modules) then it works) but this is not what I need.

loader.js looks like this:
import { resolve as resolveTs } from 'ts-node/esm'
import * as tsConfigPaths from 'tsconfig-paths'
import { pathToFileURL } from 'url'
const { absoluteBaseUrl, paths } = tsConfigPaths.loadConfig()
const matchPath = tsConfigPaths.createMatchPath(absoluteBaseUrl, paths)
export function resolve(specifier, ctx, defaultResolve) {
const match = matchPath(specifier)
return match
? resolveTs(pathToFileURL(${match}).href, ctx, defaultResolve)
: resolveTs(specifier, ctx, defaultResolve)
}
export { load, getFormat, transformSource } from 'ts-node/esm'

My tsconfig.json looks like this:
/* To learn more about this file see: https://angular.io/config/tsconfig. /
{
"compileOnSave": false,
"compilerOptions": {
"baseUrl": "./",
"paths": {
"e2e-api": [
"dist/e2e-api"
],
"e2e-api/": [
"dist/e2e-api/*"
]
},
"outDir": "./dist/out-tsc",
"forceConsistentCasingInFileNames": true,
"strict": true,
"noImplicitOverride": true,
"noPropertyAccessFromIndexSignature": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"sourceMap": true,
"declaration": false,
"downlevelIteration": true,
"experimentalDecorators": true,
"moduleResolution": "node",
"importHelpers": true,
"target": "es2020",
"module": "es2020",
"lib": [
"es2020",
"dom"
]
},
"include": [
"dist"
],
"angularCompilerOptions": {
"enableI18nLegacyMessageIdFormat": false,
"strictInjectionParameters": true,
"strictInputAccessModifiers": true,
"strictTemplates": true
}
}

[testgitdl]

The solution also works for me. The problem was that I wasn't setting correctly the experimental-specifier-resolution.
On windows now I'm able to use the paths when running Cucumber+Playwright+Angular13 tests via:
"test-bdd-chrome": "SET NODE_OPTIONS=--loader ts-node/esm --loader ./loader.js --no-warnings --experimental-specifier-resolution=node && node ./node_modules/@cucumber/cucumber/bin/cucumber.js",

[AgainPsychoX]

(You can format code in Markdown, here's tutorial: https://www.markdownguide.org/extended-syntax/#syntax-highlighting)

[AgainPsychoX]

If you get ERR_INVALID_MODULE_SPECIFIER with some solutions, make sure you use pathToFileURL or other proper URI encoding, as some characters in paths (in my case it was hash character #) can mean different things if simply appended in the URL.

Currently working code used by me:

import { pathToFileURL } from 'url';
import { resolve as resolveTs, getFormat, transformSource, load } from 'ts-node/esm';
import * as tsConfigPaths from 'tsconfig-paths'

export { getFormat, transformSource, load };

const { absoluteBaseUrl, paths } = tsConfigPaths.loadConfig()
const matchPath = tsConfigPaths.createMatchPath(absoluteBaseUrl, paths)

export function resolve(specifier, context, defaultResolver) {
	const mappedSpecifier = matchPath(specifier);
	console.log(mappedSpecifier);
	if (mappedSpecifier) {
		specifier = pathToFileURL(mappedSpecifier) + '.ts';
	}
	return resolveTs(specifier, context, defaultResolver);
}

[callumgare]

It appears there is already a PR to add support for this but unfortunately it appears progress has faulted. #1585

[RollingSnack]

The previous solution for matching .ts modules imported without an extension was to use --experimental-specifier-resolution flag, which has been removed since v19+.
I wrote the following loader as a replacement referring to the cjs loader implementation of nodejs.

// loader.js
import { isBuiltin } from 'node:module';
import { dirname } from 'node:path';
import { promisify } from 'node:util';
import { fileURLToPath, pathToFileURL } from 'node:url';

import resolveCallback from 'resolve';
import { resolve as resolveTs, load } from 'ts-node/esm';
import { loadConfig, createMatchPath } from 'tsconfig-paths';

const resolveAsync = promisify(resolveCallback);
const tsExtensions = new Set(['.tsx', '.ts', '.mts', '.cts']);

const { absoluteBaseUrl, paths } = loadConfig();
const matchPath = createMatchPath(absoluteBaseUrl, paths);

async function resolve(specifier, ctx, defaultResolve) {
  const { parentURL = pathToFileURL(absoluteBaseUrl) } = ctx;

  if (isBuiltin(specifier)) { return defaultResolve(specifier, ctx); }

  if (specifier.startsWith('file://')) { specifier = fileURLToPath(specifier); }

  let url;
  try {
    const resolution = await resolveAsync(matchPath(specifier) || specifier, {
      basedir: dirname(fileURLToPath(parentURL)),
      // For whatever reason, --experimental-specifier-resolution=node doesn't search for .mjs extensions
      // but it does search for index.mjs files within directories
      extensions: ['.js', '.json', '.node', '.mjs', ...tsExtensions],
    });
    url = pathToFileURL(resolution).href;
  } catch (error) {
    if (error.code === 'MODULE_NOT_FOUND') {
      // Match Node's error code
      error.code = 'ERR_MODULE_NOT_FOUND';
    }
    throw error;
  }

  return resolveTs(url, ctx, defaultResolve)
}

export { resolve, load };

tsconfig-paths itselft will resolve once, so the above code repeatedly the resolve operation, resulting in additional overhead.
You can also avoid it by simply replacing the path mapping and feeding all possible paths to resolveAsync like this:

import { resolve as resolvePath } from 'node:path';

let tryPaths = [specifier];
for (const [path, pathMaps] of Object.entries(paths)) {
  const match = specifier.match(`^${path.replace('*', '(.*)')}`);
  if (!match) { continue; }

  tryPaths = tryPaths.concat(pathMaps.map((pathMap) => resolvePath(
    absoluteBaseUrl,
    pathMap.replace('*', match[1] || '')
  )));
}

Replace matchPath(sepcifier) || specifier with each item in tryPaths.

[arjunyel]

I've got path mapping working for me on Node 19.6.0 node --loader @bleed-believer/path-alias/esm ./src/worker.ts this PR lets me use it in an NX monorepo sleep-written/bleed-believer#3 Hope it helps someone!

[sleep-written]

Hi, thanks for your PR!
Your changes has been reviewed and merged. And the package has been updated for anyone needs the monorepo support.

[leookun]

Did someone let it build js on production? This just seems to allow node to run directly