Rewrite relative import extensions with flag

[andrewbranch]

This PR adds --rewriteRelativeImportExtensions to support transforming module specifiers from e.g. "./utils.ts" to "./utils.js". A module specifier will be statically rewritten or shimmed during JS emit if it meets all of these criteria:

• it begins with ./ or ../
• it does not end in a declaration file name (.d.ts, .d.mts, .d.cts, .d.*.ts)
• it ends in .ts, .tsx, .mts, or .cts

Error checking

Errors are issued in an attempt to catch common mistakes:

• A module specifier will get rewritten but will break after rewriting:
  • "./foo.ts" actually resolves to ./foo.ts.ts or foo.ts/index.ts
  • "../other-project/src/index.ts" belongs to another project where outputs go to a different outDir
• A module specifier will not get rewritten but will break after emitting as-is:
  • "#blah/foo.ts" resolves to foo.ts where the .ts matches through a wildcard

Syntax support

Scenario	Example input	Operation	Example output
Import declarations	import "./foo.ts"	Rewrite	import "./foo.js", require("./foo.js")
Export declarations	export * from "./foo.ts"	Rewrite	export * from "./foo.js"
Import equals	import foo = require("./foo.ts")	Rewrite	import foo = require("./foo.js")
Import calls with qualifying literal argument	import("./foo.ts")	Rewrite	import("./foo.js")
Require calls in JS with qualifying literal argument	require("./foo.ts")	Rewrite	require("./foo.js")
Import calls with non-literal argument	import(getPath())	Shim	import(__rewriteRelativeImportExtension(getPath()))
Require calls in JS with non-literal argument	require(getPath())	Shim	require(__rewriteRelativeImportExtension(getPath()))
Import calls with non-qualifying literal argument	import("foo")	None	import("foo")
Require calls with non-qualifying literal argument	require("foo")	None	require("foo")
Require calls in TS	require("./foo.ts")	None	require("./foo.ts")
Indirected require calls	(require)("./foo.ts")	None	(require)("./foo.ts")

Limitations and future work

This PR doesn’t change how module resolution works, so it’s still possible to reference a .ts file by a .js module specifier:

// @Filename: a.ts
export {};

// @Filename: b.ts
import {} from "./a.js"; // Always ok

We discussed that it’s probably desirable to turn this functionality off under --rewriteRelativeImportExtensions (and --allowImportingTsExtensions), since these options are a strong indicator that the user is going to run the input TS files in a TS-native runtime like Bun or node --experimental-strip-types. That would be a breaking change and isn’t included in this PR.

tslib PR: microsoft/tslib#270
Fixes #59597

[andrewbranch]

@typescript-bot pack this

[typescript-bot]

Starting jobs; this comment will be updated as builds start and complete.

Command	Status	Results
pack this	✅ Started	✅ Results

[typescript-bot]

Hey @andrewbranch, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/163457/artifacts?artifactName=tgz&fileId=2225118E5057943A4B80A3A9D8FE2EA5696226BA40FE09011C7C2241BF80844302&fileName=/typescript-5.7.0-insiders.20240826.tgz"
    }
}

and then running npm install.

---

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/[email protected]".;

[typescript-bot]

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

[nicolo-ribaudo]

Hey, I was reading the table in the PR description and I'm getting confused by these two lines:

Scenario	Example input	Operation	Example output
Require calls in JS with qualifying literal argument	require("./foo.ts")	Rewrite	require("./foo.js")
Require calls in TS	require("./foo.ts")	None	require("./foo.ts")

Does it mean that require("./foo.ts") will be rewritten if it's inside a JS file, but not if it's inside a TS file?

[andrewbranch]

Yes. Plain require calls aren’t recognized as special in TS files. You’ll notice in JS that require("./foo") performs module resolution (the compiler knows the type to return), but in TS, require isn’t even allowed unless it’s declared as a global function, in which case that function’s return type is used (usually any).

[jremy42]

Just out of curiosity, I’m facing an issue where my .d.ts files don’t have an extension in the path. For example: export * as v1alpha2 from './v1alpha2/index.gen';. Why is the .ts extension mandatory to transform it into .js? Thank you.

[nyan-left]

@RyanCavanaugh

Imports in .d.ts files are allowed to use .ts extensions regardless of config, so I wouldn't really consider that a bug.

While .d.ts files may allow .ts extensions in imports without configuration, wouldn't this break backwards compatibility for libraries targeting TypeScript 4 support since allowImportingTsExtensions wasn't introduced until TypeScript 5?

[sant123]

If a path contains .jsx it is preserved even with the preserveJsx argument.

Should the regex be /\.([jt]sx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i?

This now works:

console.log(rewriteRelativeImportExtension("./main.tsx"));
console.log(rewriteRelativeImportExtension("./main.ts"));
console.log(rewriteRelativeImportExtension("./main.jsx"));
console.log(rewriteRelativeImportExtension("./main.jsx", true));
console.log(rewriteRelativeImportExtension("./main.js"));

./main.js
./main.js
./main.js
./main.jsx
./main.js

[andrewbranch]

Can you clarify your actual behavior and expected behavior?

[sant123]

Nevermind, I'm writing a plugin that is based on __rewriteRelativeImportExtension. For Typescript is fine, however for esbuild the .jsx can the transformed to .js.

[nwidynski]

@andrewbranch @RyanCavanaugh Shouldn't calls to import.meta.resolve()/require.resolve() also be shimmed as part of this flag? The MDN docs suggest this should be the case.