renamedDependencies not working with ESM

[sdegutis]

🔎 Search Terms

renamedDependencies

🕗 Version & Regression Information

• This changed between versions ______ and _______
• This changed in commit or PR _______
• This is the behavior in every version I tried, and I reviewed the FAQ for entries about _________
• I was unable to test this on prior versions because _______

⏯ Playground Link

No response

💻 Code

The compiler API option renamedDependencies seems to be unused. I put a breakpoint in it and it's never called. I can't get it to be called.

🙁 Actual behavior

The renamedDependencies option seems to not be used.

🙂 Expected behavior

The renamedDependencies would hopefully make my transformer plugin obsolete.

Additional information about the issue

It was documented in the wiki but isn't anymore.

[MartinJohns]

It's used here:

TypeScript/src/compiler/factory/utilities.ts

Lines 803 to 831 in 44d4671

	/**
	* Get the name of a target module from an import/export declaration as should be written in the emitted output.
	* The emitted output name can be different from the input if:
	* 1. The module has a /// <amd-module name="<new name>" />
	* 2. --out or --outFile is used, making the name relative to the rootDir
	* 3- The containing SourceFile has an entry in renamedDependencies for the import as requested by some module loaders (e.g. System).
	* Otherwise, a new StringLiteral node representing the module name will be returned.
	*
	* @internal
	*/
	export function getExternalModuleNameLiteral(factory: NodeFactory, importNode: ImportDeclaration | ExportDeclaration | ImportEqualsDeclaration | ImportCall, sourceFile: SourceFile, host: EmitHost, resolver: EmitResolver, compilerOptions: CompilerOptions): StringLiteral | undefined {
	const moduleName = getExternalModuleName(importNode);
	if (moduleName && isStringLiteral(moduleName)) {
	return tryGetModuleNameFromDeclaration(importNode, host, factory, resolver, compilerOptions)
	|| tryRenameExternalModule(factory, moduleName, sourceFile)
	|| factory.cloneNode(moduleName);
	}
	return undefined;
	}
	/**
	* Some bundlers (SystemJS builder) sometimes want to rename dependencies.
	* Here we check if alternative name was provided for a given moduleName and return it if possible.
	*/
	function tryRenameExternalModule(factory: NodeFactory, moduleName: LiteralExpression, sourceFile: SourceFile) {
	const rename = sourceFile.renamedDependencies && sourceFile.renamedDependencies.get(moduleName.text);
	return rename ? factory.createStringLiteral(rename) : undefined;
	}

[repo-anuj]

Hi! Thanks for bringing this up.
I also couldn't find any references to renamedDependencies being actively used within the TypeScript codebase. It doesn't seem to be invoked anywhere in the main compilation pipeline, and its absence from recent documentation suggests it might be deprecated or an unfinished feature.

Could someone from the TypeScript team clarify the intended status of renamedDependencies? Is it still supported, or is there an alternative approach you recommend for scenarios where dependency renaming is needed (such as in custom transformer plugins)?

If it's deprecated, perhaps the docs could be updated to reflect that. If not, any guidance or usage example would be greatly appreciated!

[RyanCavanaugh]

Here's how it works:

> require('typescript').transpileModule("import {foo} from 'bar'; foo;", { renamedDependencies: { bar: 'baz' } })
{
  outputText: '"use strict";\n' +
    'Object.defineProperty(exports, "__esModule", { value: true });\n' +
    'var bar_1 = require("baz");\n' +
    'bar_1.foo;\n',
  diagnostics: [],
  sourceMapText: undefined

[sdegutis]

I assumed so, but in all my testing, it just wasn't working at all, which is why I was confused:

console.log(ts.transpileModule(`import foo from 'bar'; foo;`, {
  compilerOptions: {
    module: ts.ModuleKind.ESNext,
    target: ts.ScriptTarget.ESNext,
    jsx: ts.JsxEmit.ReactJSX,
  },
  renamedDependencies: {
    'bar': 'qux',
  }
  // transformers: {
  //   after: [transformExternalModuleNames({
  //   })]
  // }
}).outputText)

import foo from 'bar';
foo;

[sdegutis]

When I comment both module and target out, it works:

console.log(ts.transpileModule(`import foo from 'bar'; foo;`, {
  compilerOptions: {
    // module: ts.ModuleKind.ESNext,
    // target: ts.ScriptTarget.ESNext,
    jsx: ts.JsxEmit.ReactJSX,
  },
  renamedDependencies: {
    'bar': 'qux',
  }
  // transformers: {
  //   after: [transformExternalModuleNames({
  //   })]
  // }
}).outputText)

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
var bar_1 = require("qux");
bar_1.default;

With both or either of them left in, it works not.

Signed,
Confused.

[sdegutis]

Okay my takeaways about how this works:

1. It seems to only work with module being anything other than ES*
2. It does not do prefix/lib replacement (which I needed), only exact replacement
3. target doesn't seem to matter, except that ES5 seems to imply module = AMD or something

@RyanCavanaugh Could we repurpose this issue to make this do substring-replacement or prefix/lib replacement? I can send a PR, pretty sure I already signed a CA years ago and committed before. (That could be VS Code though, I don't remember.)

[sdegutis]

Oh also and to make it work with ESNext/etc.

[RyanCavanaugh]

I really have to recommend using some other tool like esbuild if you're doing something that requires modifying module paths as part of transpilation. This part of the API is very under-utilized and isn't something we're going to carry forward in TypeScript 7. I don't want you to spend time digging further into something that's ultimately going to be a dead end.

[sdegutis]

Thanks, that's fine. I'll just keep using my plugin

[sdegutis]

@RyanCavanaugh One thing to consider might change your mind about this being out of scope of TypeScript. The web is slowly but surely moving to ESM. It may take another 10 years before it's caught on, but it's stable, and with module-preloads it's currently just as efficient as bundling. Right now, my TypeScript Compiler API plugin just remaps module names to CDN versions, like so: renamedDependencies: { 'matter-js': 'https://cdn.jsdelivr.net/npm/matter-js@0.20.0/+esm' } -- this feature you have is currently enough for this use-case, which essentially modernizes the feature and brings it back into relevance. But considering also that default-file imports are essentially deprecated in Node.js, we will often need to import foo/index.js instead of just foo, so this feature needs to be able to transform library names, or at least prefixes. I do think it would be worthwhile to make this a first-class feature. If you agree, feel free to reopen this issue and let me know and I'll submit a PR.

[sdegutis]

Yeah I've made up my mind, I'm going to get renamedDependencies working (as-is) with ESM and send a PR, regardless of what you do next. In the same PR I'm also going to add it as a top-level key in tsconfig.json so that I can use it with tsc. And I'll probably do the same in the Go repo, I've been wanting an excuse to pick up Go again ever since it got generics.