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.

[bakkot]

The original issue was locked; it would be nice for someone with permissions to comment there so that people who were following there get this update.

[jlmart88]

@RyanCavanaugh I happened upon your final post here: #49083 (comment) minutes before you commented and referenced this PR.

I'm curious what changed from your reasoning a year ago as to why this would never be a feature?

[RyanCavanaugh]

NodeJS shipping --experimental-strip-types means there's now an actual runtime scenario where you need both JS and TS extensions

[RyanCavanaugh]

Note that if you're using this in any other situation than that, you likely have a misconfiguration or misunderstanding of some kind, and I'll be telling you as much in a future issue when you report that e.g. this "doesn't work" across package boundaries.

[AlttiRi]

I have tested TS 5.7.0-dev.

It does not rewrite .d.ts files.

My library preset on 5.6.2:

    /* Library preset */
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "noEmit": false,
    "declaration": true,

and new one on 5.7.0-dev:

    /* Library preset */
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "allowImportingTsExtensions": true,      // <- new
    "rewriteRelativeImportExtensions": true, // <- new
    "noEmit": false,
    "declaration": true,

It works, I can use tsc (after changing .js to .ts in imports in all files).

Also, now I can run TS files with deno without using --unstable-sloppy-imports which prints annoying warnings.

However, imports inside .d.ts files have .ts ending now. There were no rewriting.

Or is it OK? (I didn't check if there would be .d.ts files to work correctly after installing a package with such .d.ts files.)

Anyway, I think that both configs should produce absolutely the same result (.js and .d.ts files) after using tsc.

[RyanCavanaugh]

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

[AlttiRi]

It's a bug. Non-rewritten imports in d.ts. break (partially) the code assistance in an IDE.

It's OK:

(npm install @alttiri/[email protected])

After using rewriteRelativeImportExtensions:

(npm install @alttiri/[email protected] --registry=https://npm.pkg.github.com)

In this case, the IDE no longer highlights the function names, nor does it show the function signature.

The imports in .d.ts also must be rewritten.

Because all d.ts files of libs are compiled with tsc have imports end with .js, never with .ts.

Because allowImportingTsExtensions was never compatible with "moduleResolution": "NodeNext" + "noEmit": false" (until this new rewriteRelativeImportExtensions appeared.)

[AlttiRi]

Also, it currently (?) does not support aliases which resolve to a relative path.

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["../*"]
    }
  }
}

I get the follow error for import {sleep} from "@/index.ts";:

TS2877: This import uses a '.ts' extension to resolve to an input TypeScript file, but will not be rewritten during emit because it is not a relative path.

[RyanCavanaugh]

Also, it currently (?) does not support aliases which resolve to a relative path.

This is 100% intentional

[AlttiRi]

Is it a problem to resolve the alias first and only after that check if it is a relative path or not?

It doesn't seem like something that is difficult to implement. Just only one extra simple action.

[RyanCavanaugh]

I don't think the setup you have there works under --experimental-strip-types. #59767 (comment)

[AlttiRi]

Okay, I have checked it with the latest Node.js (v22.9.0) too (I tested it with Deno before).

It works (as expected).

[RyanCavanaugh]

I can't replicate what you're doing there

// with
// import * as bar from "./bar.ts";

node --experimental-strip-types foo.ts
hi

vs

// with
// import * as bar from "@/bar.ts";
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@/bar.ts' imported from D:\Throwaway\est-test\foo.ts

The purpose of the flag is to rewrite paths which are syntactically relative, not "semantically" relative (whatever that would even mean).

[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).