TS has no way to import native modules with ESM syntax

[CamJN]

🔎 Search Terms

• --experimental-addon-modules
• ESM
• native extension
• .node

🕗 Version & Regression Information

• This has always been the case
• This is the behaviour in every version I tried, and I checked the FAQ for entries about importing native modules but none exist or I missed them

⏯ Playground Link

I don't see any way to include a native extension in the playground, so that's not possible. Here's a repo: https://github.com/getargv/getargv.js/tree/feature/esm

💻 Code

import addon from '../build/Release/getargv_native.node';

🙁 Actual behavior

$ npm run build

> @camjn/getargv@0.0.31 prebuild
> tsc

lib/binding.ts:3:19 - error TS2307: Cannot find module '../build/Release/getargv_native.node' or its corresponding type declarations.

3 import addon from '../build/Release/getargv_native.node';
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

🙂 Expected behavior

Since node offers the --experimental-addon-modules flag and every node version from node20 on supports esm syntax, I expect to be able to use esm syntax to import native modules in typescript too.

Additional information about the issue

No response

[RyanCavanaugh]

Ambient declarations can use wildcard paths, so you can do e.g.

declare module "*/getargv_native.node" {
    export const addon: string;
}

in a separate declaration file to provide this info

[CamJN]

Sorry for being thick, but I think you're saying to create a bindings.d.ts with something like this:

import { GetArgv } from './types';

declare module "*/getargv_native.node" {
    export const addon: GetArgv;
}

and then import addon from '../build/Release/getargv_native.node'; should work? Because I still get the same error:

typescript [2307]: Cannot find module '../build/Release/getargv_native.node' or its corresponding type declarations.

Sticking it all in one file gives: Invalid module name in augmentation, module '*/getargv_native.node' cannot be found. on the declare module line.

[RyanCavanaugh]

The import needs to be inside the declare module block, though it can't use relative paths. You'd have to re-export GetArgv from a declare global block in (yet another) separate file

[CamJN]

This makes the GetArgv type visible within the declare module block, yes.

declare module "*/getargv_native.node" {
  import { GetArgv } from './types';
  const addon: GetArgv;
  export default addon;
}
import addon from '../build/Release/getargv_native.node';

But it doesn't do anything about the paths.

You'd have to re-export GetArgv from a declare global block in (yet another) separate file

Can you please either go into more detail or point at some docs I can read about this?

[RyanCavanaugh]

RyanCavanaugh/getargv.js@4ada44a

[CamJN]

Oh wow thanks!