loader: add experimental text import

[efekrskl]

Closes #62082

Adds support for text import under --experimental-import-text flag.

Example:

import text from './file.txt' with { type: 'text' };

Import text is a Stage 3 TC39 proposal

Deno supports text imports with --unstable-raw-imports.
Bun supports text imports directly.

Not entirely sure what the current stance is on not-yet-landed proposals, but putting this up for discussion and feedback.

[nodejs-github-bot]

Review requested:

• @nodejs/config
• @nodejs/loaders

[bakkot]

Note that the import-bytes proposal requires producing Uint8Arrays backed by immutable ArrayBuffers, which are not yet supported in V8. I would be hesitant to ship this with mutable backing buffers, even flagged as experimental, lest people come to rely on that.

Text imports don't have the same problem.

[efekrskl]

Note that the import-bytes proposal requires producing Uint8Arrays backed by immutable ArrayBuffers, which are not yet supported in V8. I would be hesitant to ship this with mutable backing buffers, even flagged as experimental, lest people come to rely on that.

Text imports don't have the same problem.

That's a great point, looks like I've missed that. I've removed bytes related part of the code. Thank you!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.63%. Comparing base (a7f487f) to head (8c0248f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #62300   +/-   ##
=======================================
  Coverage   89.63%   89.63%           
=======================================
  Files         708      708           
  Lines      220402   220447   +45     
  Branches    42271    42293   +22     
=======================================
+ Hits       197551   197598   +47     
+ Misses      14706    14701    -5     
- Partials     8145     8148    +3     

Files with missing lines	Coverage Δ
lib/internal/modules/esm/assert.js	100.00% <100.00%> (ø)
lib/internal/modules/esm/get_format.js	95.20% <100.00%> (+0.37%)	⬆️
lib/internal/modules/esm/loader.js	99.69% <100.00%> (ø)
lib/internal/modules/esm/translators.js	97.72% <100.00%> (+0.03%)	⬆️
src/node_options.cc	76.63% <100.00%> (+0.12%)	⬆️
src/node_options.h	97.50% <100.00%> (-0.49%)	⬇️

... and 29 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[GeoffreyBooth]

Note that the import-bytes proposal requires producing Uint8Arrays backed by immutable ArrayBuffers, which are not yet supported in V8. I would be hesitant to ship this with mutable backing buffers, even flagged as experimental, lest people come to rely on that.
Text imports don't have the same problem.

That's a great point, looks like I've missed that. I've removed bytes related part of the code. Thank you!

This is really good knowledge that would be good to preserve somewhere. Maybe add a comment near the most appropriate spot in the new code, such as where the bytes support would be, to note that we shouldn’t add bytes support before immutable ArrayBuffers exist in V8? That way if someone later on comes by to add bytes, they'll stumble upon the comment in the code.

[pdeveltere]

in loader.js, you can add:

/**
 * @typedef {'builtin'|'commonjs'|'json'|'module'|'text'|'wasm'} ModuleFormat
 */

[efekrskl]

Note that the import-bytes proposal requires producing Uint8Arrays backed by immutable ArrayBuffers, which are not yet supported in V8. I would be hesitant to ship this with mutable backing buffers, even flagged as experimental, lest people come to rely on that.
Text imports don't have the same problem.

That's a great point, looks like I've missed that. I've removed bytes related part of the code. Thank you!

This is really good knowledge that would be good to preserve somewhere. Maybe add a comment near the most appropriate spot in the new code, such as where the bytes support would be, to note that we shouldn’t add bytes support before immutable ArrayBuffers exist in V8? That way if someone later on comes by to add bytes, they'll stumble upon the comment in the code.

Yeah makes sense, I've added a comment right below formatTypeMap

[sffc]

Please add a test for what happens when you try to import a binary data file such as an image.png or mod.wasm.

I encourage Node.js to take a strict view here. The following code should throw an exception

import text from "image.png" with { type: "text" };

[pdeveltere]

Hmm, I'm not so sure. I would just allow any file to be read as text. You never know it might have a use case. And implementing a list of potential extensions which don't make sense could be a never ending process?

[ljharb]

I'm really not sure why it should - if there's a text representation of a file, it should give it. If it's nonsense, that's the developer's problem to solve.

[sffc]

Hmm, I'm not so sure. I would just allow any file to be read as text. You never know it might have a use case.

Replacement characters render the text form of a non-text file unusable and unrecoverable, so it's hard to think of a use case.

And implementing a list of potential extensions which don't make sense could be a never ending process?

I don't suggest filtering by extension. I suggest throwing an exception if any non-text byte is encountered when reading the file.

[ljharb]

Which bytes are always, universally, non-text?

[ljharb]

but valid javascript strings can have lone surrogates, so i'm a bit confused why we'd want to do either one - meaning, throwing kills use cases, and silently substituting results in artificially well-formed utf8?

[sffc]

When reading files, it's always necessary to push them through a text decoder, except the unusual case where the file is stored on disk as UTF-16. There is no such thing as lone surrogates in UTF-8.

[efekrskl]

I'm a bit unsure about throwing here. Neither Deno nor Bun throw on invalid UTF-8 in this case, so I'm leaning toward keeping Node aligned.

Of course, I'm open to being challenged if there's a strong reason.

[sffc]

Do Deno and Bun ship this feature? It is not a standard feature yet; it is moving through committee. Node should do what's right, not what implementations of a non-standard feature have done.

[bakkot]

It's unflagged in Bun since April 2024, and flagged in Deno since June 2025.

That doesn't necessarily mean anyone's depending on being able to import invalid UTF-8 with replacement characters instead of an error, though.

[bakkot]

Does this actually need to be behind an experimental flag? The proposal is stage 3, and pretty simple.

[ShogunPanda]

Does this actually need to be behind an experimental flag? The proposal is stage 3, and pretty simple.

I agree. We don't have to use experimental for anything, especially since it will require additional burden about promoting to stable at some point.

Since the feature is low risk and unlikely to change in the future (which I how I envision "experimental" is meant to use), I would directly insert as stable.

[GeoffreyBooth]

I think this should be introduced as experimental. I can’t think of any modules features we’ve introduced directly as stable. Modules features have compatibility concerns with other runtimes; we want to see how import-type-text behaves in Deno and Bun and browsers before we promote our version to stable. There’s also the issue that as soon as our version is stable, people start relying on it in published public npm packages; we want to make sure we have ours fully correct before that happens.

[ShogunPanda]

I think this should be introduced as experimental. I can’t think of any modules features we’ve introduced directly as stable. Modules features have compatibility concerns with other runtimes; we want to see how import-type-text behaves in Deno and Bun and browsers before we promote our version to stable. There’s also the issue that as soon as our version is stable, people start relying on it in published public npm packages; we want to make sure we have ours fully correct before that happens.

I'm honestly fine with this as well.
My only note here is that we need to establish a policy to continously review experimental modules and don't leave them in that state forever.

[slorber]

I think this should be introduced as experimental. I can’t think of any modules features we’ve introduced directly as stable.

Marking this as experimental is one thing, but gating it behind a flag is another. Couldn't you just mark it as experimental but not gate it?

Afaik, not all Node.js experimental features are behind a flag, and a flag doesn't encourage the community to test this feature and share feedback.

Modules features have compatibility concerns with other runtimes; we want to see how import-type-text behaves in Deno and Bun and browsers before we promote our version to stable. There’s also the issue that as soon as our version is stable, people start relying on it in published public npm packages; we want to make sure we have ours fully correct before that happens.

If an npm package adopts this and you have to change the semantics, that can be considered a bug fix, not a breaking change, considering there's a public/std spec you need to conform to. If there are gaps in the spec that lead different implementations to behave differently, that's another problem 😅

[efekrskl]

I initially put it behind a flag because this PR was implementing both bytes and text import, but now that bytes implementation is removed, I don't mind removing the flag. We should still label it as experimental though

[GeoffreyBooth]

I initially put it behind a flag because this PR was implementing both bytes and text import, but now that bytes implementation is removed, I don't mind removing the flag. We should still label it as experimental though

Please introduce this behind a flag and cite it in the docs as experimental status 1.0 - Early development. This is how all modules features are introduced.

[efekrskl]

I initially put it behind a flag because this PR was implementing both bytes and text import, but now that bytes implementation is removed, I don't mind removing the flag. We should still label it as experimental though

Please introduce this behind a flag and cite it in the docs as experimental status 1.0 - Early development. This is how all modules features are introduced.

Fair enough. Thanks for taking time and elaborating on your initial comments! I took some time to better understand the flow and I see your point. Would appreciate another review

I'll address the rest of the comments later

[GeoffreyBooth]

BTW for those of you asking about experimental statuses and flags, you can look in the GitHub history and you'll find the PRs related to the original implementation of import assertions, which was Stage 3 at the time for a syntax assert { type: 'json' }. Node went so far as to not just implement it but then to unflag it, and then TC39 changed the syntax from assert to with and Node re-flagged the feature and eventually removed the old assert syntax. So something being in Stage 3 (especially around import assertions/import attributes) shouldn't be considered a solid signal that the feature is ready to be considered stable.

[efekrskl]

I initially put it behind a flag because this PR was implementing both bytes and text import, but now that bytes implementation is removed, I don't mind removing the flag. We should still label it as experimental though

Please introduce this behind a flag and cite it in the docs as experimental status 1.0 - Early development. This is how all modules features are introduced.

I've added the docs for the flag 👍

[aduh95]

There's a conflict, can you please rebase the PR?

This is coming via V8 any day though

I could be wrong but I don't see what change V8 could do related to that, it already supports the with {} syntax, AFAIK it's up to Node.js to add support for the 'text' value, the same way we have to handle type: 'json' in Node.js.

[AugustinMauroy]

oh yeah aduh95 had right that nodejs code that handle loading of json module.
So LGMT for this pr.

But https://github.com/tc39/proposal-source-phase-imports will need v8 thing

source ≠ type text

[efekrskl]

Yes, this is similar to how json is handled on our end.

I've resolved the conflict

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/74308/

[JakobJingleheimer]

AFAIK it's up to Node.js to add support for the 'text' value

https://issues.chromium.org/issues/494350643

☝️ The "parent", which links to PRs etc

The V8-specific PR that would bring this to node is https://chromium-review.googlesource.com/c/v8/v8/+/7844854

[bakkot]

The V8-specific PR that would bring this to node is https://chromium-review.googlesource.com/c/v8/v8/+/7844854

Unless I'm missing something, that's just the implementation in the d8 shell? I don't think that will affect node at all. I think this is something embedders have to do on their own, same as for json despite that also being implemented in d8. The actual implementation of text imports in Chrome is in this CL.

[nodejs-github-bot]

Landed in 54296cb

[JakobJingleheimer]

Oh. That's unexpected. In that case, nevermind—carry on.