[BUG]: Documentation for loading stripe pure not correct for ESM environments.

[RobertSandiford]

What happened?

The sample code:

import {loadStripe} from '@stripe/stripe-js/pure';

attempts to import a directory, which is not valid in ESM. The import needs to reference @stripe/stripe-js/pure/index.js or @stripe/stripe-js/pure/index.mjs to work in a true ESM environment.

Note also that the file @stripe/stripe-js/pure/index.mjs is invalid in ESM too because it attempts to import a file without an extension which is not allowed in ESM: export * from '../dist/pure';

importing '@stripe/stripe-js/pure/index.js' does work currently, although node is importing the CJS module and handling the conversion to the ESM environment (this is mostly fine, but perhaps it won't allow treeshaking during bundling).

Environment

Windows

Reproduction

https://github.com/RobertSandiford/stripe-pure-esm-repro

[brendanm-stripe]

@RobertSandiford can you confirm the exact version you are using an runtime? I see ^5.5.0 in your repro, but I'm a bit confused about the mismatch on what you described here:

Note also that the file @stripe/stripe-js/pure/index.mjs is invalid in ESM too because it attempts to import a file without an extension which is not allowed in ESM: export * from '../dist/pure';

Because @stripe/stripe-js/pure/index.mjs does use a file extension on import (unpkg):

export * from '../dist/pure.mjs';

So I thought the fix based on your description would be to add that extension and recommend using the explicit index.mjs as you show, but that appears to already be in place.

[RobertSandiford]

@RobertSandiford can you confirm the exact version you are using an runtime? I see ^5.5.0 in your repro, but I'm a bit confused about the mismatch on what you described here:

Note also that the file @stripe/stripe-js/pure/index.mjs is invalid in ESM too because it attempts to import a file without an extension which is not allowed in ESM: export * from '../dist/pure';

Because @stripe/stripe-js/pure/index.mjs does use a file extension on import (unpkg):

export * from '../dist/pure.mjs';

So I thought the fix based on your description would be to add that extension and recommend using the explicit index.mjs as you show, but that appears to already be in place.

Hi Brendan. v5.5.0

Yes you're right, I made a slight error.

pure/index.mjs is correct: export * from '../dist/pure.mjs';
But its type declaration file pure/index.d.mts is incorrect: export * from '../dist/pure'; - this comes up when I control click on the import target when using TS, hence my error.

So with the current code TS tries to resolve the invalid import in the declaration file and reports a type error, but it does work at runtime. You can see this in the 3rd import in the repro.

[brendanm-stripe]

Ah, gotcha. NP - thanks for clarifying.

Ok, so it sounds like the expected change to resolve the TS error here would be revising /pure/index.d.mts (code) to import ../dist/pure.d.mts .

Does that match your expectations?

[RobertSandiford]

Ah, gotcha. NP - thanks for clarifying.

Ok, so it sounds like the expected change to resolve the TS error here would be revising /pure/index.d.mts (code) to import ../dist/pure.d.mts .

Does that match your expectations?

Hi Brendan, I checked a .d.ts file generated by typescript and the import in index.d.mts would just be to the .mjs file, not the .d.mts: export * from '../dist/pure.mjs';

Trying to import the .d.mts files gives an error A declaration file cannot be imported without 'import type'. Did you mean to import an implementation file '../dist/pure.mjs' instead? but that like prevent exporting the values/functions/objects and only export the types, so not what we want.

I've tried the fix by editing index.d.mts in my node_modules folder and it fixes the first import but leads to a the same error again when importing './shared' from pure.d.mts, and then again when fixing that. It should just need the same change being made throughout the .d.mts files. Any references to directories should be changed to dir/index.mjs.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.