Support importing types from a `.mts` file from within a CommonJS file.

[Jason3S]

🔍 Search Terms

"commonjs", "import", "type", "module"

✅ Viability Checklist

• [X] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [X] This wouldn't change the runtime behavior of existing JavaScript code
• [X] This could be implemented without emitting different JS based on the types of the expressions
• [X] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [X] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• [X] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Proposal: Allow importing pure types from .mts files from a CommonJS file.

The current behavior generates an unnecessary / incorrect error since no require will be emitted.

Current error:

Please note, future versions of Node will support requiring an ESM module if a there is not a top level await. See:

• module: support require()ing synchronous ESM graphs by joyeecheung · Pull Request #51977 · nodejs/node

📃 Motivating Example

src/code.cts

import type { EntityId, Entity, User } from './models.mjs';

export function userName(user: User): string {
    return user.name;
}

src/models.mts

export type EntityId = string;

export interface Entity {
    id: EntityId;
}

export interface User extends Entity {
    name: string;
}

💻 Use Cases

1. What do you want to use this for? In mixed code bases (especially as they transition from CommonJS to ESM) it is often necessary export the types from a module that are used in CommonJS files.
2. What shortcomings exist with current approaches? All shared types must be declared in CommonJS files or inferred using Awaited.
3. What workarounds are you using in the meantime? Declaring shared types in CommonJS files.

[RyanCavanaugh]

Duplicate #52529 edit: maybe?

[RyanCavanaugh]

@andrewbranch points out that the concerns in the linked issue are specific to resolution hitting different targets in upstream packages due to revisions in their package jsons, but this argument doesn't apply at all to local relative paths

[andrewbranch]

The currently intended behavior is that you’re supposed to silence this error by adding with { "resolution-mode": "import" } to assert that you’re doing what you’re doing on purpose. At minimum, we need to update this error message to suggest that workaround, but I was finding it hard to construct a message that adequately explains what’s wrong with this code, since I’m still somewhat skeptical that there’s anything wrong with this code.

[jakebailey]

I'm confused; isn't the context of this issue https://github.com/nodejs/node/pull/51977, such that when that's "final", we need to have a new module resolution mode which re-allows require(ESM)? And that this issue isn't about anything else?

(Hm, maybe not, as the above was just a "side point" of sorts...)

[Jason3S]

@andrewbranch,

with { "resolution-mode": "import" }

This solves the my main issue. I did search for this, but wasn't able to figure it out based upon #53656. I was also trying to use verbatimModuleSyntax, but that doesn't work with CommonJS files.

I completely missed typescriptlang.org Stable Support resolution-mode in Import Types. I knew about with { type: "json" }.

By the way, the "value" of "resolution-mode" doesn't seem to matter for local files.

This works fine. src/code.cts

import type { User } from './models.mts' with { "resolution-mode": "require" };

Which leads to the question of why resolution-mode is necessary for local files.

@jakebailey,

I'm confused; isn't the context of this issue nodejs/node#51977, such that when that's "final", we need to have a new module resolution mode which re-allows require(ESM)? And that this issue isn't about anything else?

(Hm, maybe not, as the above was just a "side point" of sorts...)

It is a "side point", I was using it as part of the argument that importing ESM files from a CJS file is necessary to support. Given that, it would also preclude the need for with { "resolution-mode": "import" }

[andrewbranch]

Yeah, if that lands without a flag, there will be a new module mode / nodenext will be updated to support it without error. There’s nothing to do on that front yet.

[RyanCavanaugh]

We should at least update the error message to suggest the resolution mode assertion

[Jason3S]

It looks like Node 22 includes require('./file.mjs') support: Support require()ing synchronous ESM graphs.

[andrewbranch]

Under an experimental flag. nodenext won’t be updated until it lands unflagged.