Documentation missing for Node.js ES Modules & Top-Level Await

[AaronFriel]

I was looking for our documentation on how to enable ES Modules and top-level await, but it looks like the instructions are missing from "pulumi.com". I did find a couple comments on relevant issues.

• https://github.com/pulumi/pulumi/issues/5161#issuecomment-1010018506
• https://github.com/pulumi/pulumi/issues/4130#issuecomment-1002868483

These comments show changes users need to make to tsconfig.json, package.json, and pulumi.yaml to make these features work.

I searched for:

• site:www.pulumi.com ESNext
• site:www.pulumi.com ES Modules
• site:www.pulumi.com javascript OR typescript top-level await
  • Below the fold, this blog post is relevant, but links to the above two issues: https://www.pulumi.com/blog/pulumi-release-notes-66/#support-using-native-es-modules-as-pulumi-scripts

I think what we need to document would appear on our JavaScript/Node.js SDK page: https://www.pulumi.com/docs/languages-sdks/javascript/

Going a bit further, I wonder if we should add a template for typescript-esm and javascript-esm.

[scottslowe]

@interurban Assigning to you, probably needs to go to the Docs board

[awoimbee]

Note: Using ts-node/esm is slow and all typescript compilation errors to be reported as TypeError: Cannot convert object to primitive value. Using tsx solves that:

runtime:
  name: nodejs
  options:
    nodeargs: "--import tsx"

See Slack convo

[rulatir]

The Cannot convert object to primitive value is pervasive, crippling, and intrinsic to Pulumi. It is completely unrelated to the TS loader used. I switched to tsx and it persists.

[aecorredor]

+1 for nodeargs: "--import tsx". That worked for me after having struggled when looking at Pulumi TS docs. This thread is the first one that comes up in google, but unfortunately doesn't have the full information about what's needed to get ESM working.