loader: add experimental text import by efekrskl · Pull Request #62300 · nodejs/node

efekrskl · 2026-03-17T18:11:44Z

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 · 2026-03-17T18:11:50Z

Review requested:

@nodejs/config
@nodejs/loaders

bakkot · 2026-03-18T02:14:53Z

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 · 2026-03-20T18:41:38Z

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 · 2026-03-20T22:02:37Z

Codecov Report

❌ Patch coverage is 94.33962% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.70%. Comparing base (06a8240) to head (4a5953c).
⚠️ Report is 76 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/modules/esm/load.js	78.57%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62300      +/-   ##
==========================================
+ Coverage   89.68%   89.70%   +0.01%     
==========================================
  Files         676      692      +16     
  Lines      206578   214212    +7634     
  Branches    39555    41123    +1568     
==========================================
+ Hits       185267   192154    +6887     
- Misses      13446    14112     +666     
- Partials     7865     7946      +81

Files with missing lines	Coverage Δ
lib/internal/modules/esm/assert.js	`100.00% <100.00%> (ø)`
lib/internal/modules/esm/resolve.js	`99.05% <100.00%> (+<0.01%)`	⬆️
lib/internal/modules/esm/translators.js	`97.70% <100.00%> (+0.03%)`	⬆️
src/node_options.cc	`76.49% <100.00%> (+0.04%)`	⬆️
src/node_options.h	`97.96% <100.00%> (+0.03%)`	⬆️
lib/internal/modules/esm/load.js	`90.67% <78.57%> (-0.81%)`	⬇️

... and 110 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 · 2026-03-20T22:12:13Z

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.

lib/internal/modules/esm/assert.js

GeoffreyBooth · 2026-03-20T22:17:43Z

lib/internal/modules/esm/get_format.js

+function getFormatFromImportAttributes(importAttributes) {
+  if (
+    !importAttributes ||
+    !ObjectPrototypeHasOwnProperty(importAttributes, 'type') ||
+    typeof importAttributes.type !== 'string'
+  ) {
+    return undefined;
+  }
+
+  if (
+    getOptionValue('--experimental-import-text') &&
+    importAttributes.type === 'text'
+  ) {
+    return 'text';
+  }
+
+  return undefined;
+}


We already support with { type: 'json' }. This seems to introduce a new pattern, rather than following the existing one?

Good catch, the reason is JSON imports are format led (.json/MIME), whereas for text imports anything can be imported as text (regardless of .txt/MIME). So we needed to have a separate mapping

I'm open for ideas though. Maybe we can make this more clear with a comment

Agreed that it should have a new mapping, but in general we want to follow the existing patterns of the cocebase. Don’t create a new code path for handling modules of varying formats; we already have a path for with { type: 'json' } so text should work the same way, only diverging where it needs to because of the type. For example, JSON didn’t require getFormatFromImportAttributes so this function shouldn’t be needed to add support for text.

Makes sense, thanks for the guidance.

I've updated the patch, wdyt?

pdeveltere

in loader.js, you can add:

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

pdeveltere · 2026-03-26T13:24:05Z

lib/internal/modules/esm/get_format.js

 function getFileProtocolModuleFormat(url, context = { __proto__: null }, ignoreErrors) {
  const { source } = context;
  const ext = extname(url);



Suggested change

// If the caller explicitly requests text format via import attributes, honour it regardless of file extension.

if (context.importAttributes?.type === 'text') {

return 'text';

}

pdeveltere · 2026-03-26T13:24:49Z

lib/internal/modules/esm/get_format.js

    ) !== null
  ) { return 'module'; }
  if (mime === 'application/json') { return 'json'; }
  if (mime === 'application/wasm') { return 'wasm'; }


Suggested change

if (mime === 'application/wasm') { return 'wasm'; }

if (RegExpPrototypeExec(/^\s*text\/plain\s*(;\s*charset=utf-?8\s*)?$/i, mime) !== null) { return 'text'; }

efekrskl · 2026-03-29T11:35:36Z

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 · 2026-04-02T21:49:37Z

test/es-module/test-esm-import-text.mjs

+await assert.rejects(
+  import('../fixtures/file-to-read-without-bom.txt'),
+  { code: 'ERR_UNKNOWN_FILE_EXTENSION' },
+);


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" };

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?

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.

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.

bakkot · 2026-04-02T21:49:47Z

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

ShogunPanda · 2026-04-03T05:08:32Z

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 · 2026-04-06T00:07:00Z

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.

GeoffreyBooth · 2026-04-06T04:46:59Z

lib/internal/modules/esm/assert.js

  'module': kImplicitTypeAttribute,
  'wasm': kImplicitTypeAttribute, // It's unclear whether the HTML spec will require an type attribute or not for Wasm; see https://github.com/WebAssembly/esm-integration/issues/42


Since this map is never exported, I think it can have experimental formats? Then we won’t need to override it or check in so many places.

Suggested change

'module': kImplicitTypeAttribute,

'wasm': kImplicitTypeAttribute, // It's unclear whether the HTML spec will require an type attribute or not for Wasm; see https://github.com/WebAssembly/esm-integration/issues/42

'module': kImplicitTypeAttribute,

'text': 'text',

'wasm': kImplicitTypeAttribute, // It's unclear whether the HTML spec will require an type attribute or not for Wasm; see https://github.com/WebAssembly/esm-integration/issues/42

GeoffreyBooth · 2026-04-06T04:47:39Z

lib/internal/modules/esm/assert.js

+// NOTE: Don't add bytes support yet as it requires Uint8Arrays backed by immutable ArrayBuffers,
+// which V8 does not support yet.
+// see: https://github.com/nodejs/node/pull/62300#issuecomment-4079163816
+
+function getFormatType(format) {
+  if (format === 'text' && getOptionValue('--experimental-import-text')) {
+    return 'text';
+  }
+
+  return formatTypeMap[format];
+}


If you accept my previous suggestion, then this function is unnecessary . . .

GeoffreyBooth · 2026-04-06T04:48:04Z

lib/internal/modules/esm/assert.js

    }
  }
-  const validType = formatTypeMap[format];
+  const validType = getFormatType(format);


. . . and this change can be reverted . . .

Suggested change

const validType = getFormatType(format);

const validType = formatTypeMap[format];

GeoffreyBooth · 2026-04-06T04:51:08Z

lib/internal/modules/esm/assert.js

+  if (!ArrayPrototypeIncludes(supportedTypeAttributes, type) &&
+      !(type === 'text' && getOptionValue('--experimental-import-text'))) {


. . . and this change can be reverted . . .

Suggested change

if (!ArrayPrototypeIncludes(supportedTypeAttributes, type) &&

!(type === 'text' && getOptionValue('--experimental-import-text'))) {

if (!ArrayPrototypeIncludes(supportedTypeAttributes, type)) {

GeoffreyBooth · 2026-04-06T04:54:25Z

lib/internal/modules/esm/load.js

+      if (isExperimentalTextImport(importAttributes)) {
+        format = 'text';
+      }
+
      // Now that we have the source for the module, run `defaultGetFormat` to detect its format.
-      format = defaultGetFormat(urlInstance, context);
+      format ??= defaultGetFormat(urlInstance, context);


Why is this if added here? We don’t do this for JSON. This deviates from the pattern and seems suspicious, like you’re adding something here that should be somewhere else; perhaps within defaultGetFormat?

GeoffreyBooth · 2026-04-06T04:54:57Z

lib/internal/modules/esm/load.js

+    if (format == null && isExperimentalTextImport(importAttributes)) {
+      format = 'text';
+    }


Ditto here.

GeoffreyBooth · 2026-04-06T04:56:32Z

lib/internal/modules/esm/resolve.js

+  let format = defaultGetFormatWithoutErrors(url, context);
+  if (getOptionValue('--experimental-import-text') &&
+      importAttributes?.type === 'text') {
+    format = 'text';
+  }
+
  return {
    __proto__: null,
    // Do NOT cast `url` to a string: that will work even when there are real
    // problems, silencing them
    url: url.href,
-    format: defaultGetFormatWithoutErrors(url, context),
+    format,


Why are we now determining format within defaultResolve? The previous pattern did it within defaultGetFormatWithoutErrors; perhaps that’s a better place for it?

GeoffreyBooth · 2026-04-06T04:58:02Z

lib/internal/modules/esm/translators.js

 });
+
+// Strategy for loading source as text.
+translators.set('text', function textStrategy(url, translateContext) {


When strip-types was experimental, how were these handled? Were the translators just never set at all if the flag wasn’t passed, or would they throw within the function if the flag wasn’t passed, or something else?

ShogunPanda · 2026-04-06T06:38:09Z

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.

efekrskl added 2 commits March 17, 2026 18:49

loader: introduce --experimental-raw-imports flag and implementation

66a1503

loader: --experimental-raw-imports flag tests

a392f74

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Mar 17, 2026

loader: remove bytes implementation

2da51d1

efekrskl changed the title ~~loader: add experimental text and bytes import~~ loader: add experimental text import Mar 20, 2026

efekrskl marked this pull request as ready for review March 20, 2026 18:40

GeoffreyBooth reviewed Mar 20, 2026

View reviewed changes

linusg mentioned this pull request Mar 23, 2026

Implementation tracking tc39/proposal-import-text#12

Open

10 tasks

pdeveltere reviewed Mar 26, 2026

View reviewed changes

doc: add note about not implementing bytes yet

7fd27d8

efekrskl added 3 commits March 29, 2026 13:40

lint

5c3addd

loader: remove alternative format mapping

63428bb

loader: revert context changes

4a5953c

sffc reviewed Apr 2, 2026

View reviewed changes

GeoffreyBooth reviewed Apr 6, 2026

View reviewed changes

+// If the caller explicitly requests text format via import attributes, honour it regardless of file extension.
+  if (context.importAttributes?.type === 'text') {
+    return 'text';
+  }


	if (mime === 'application/wasm') { return 'wasm'; }
	if (RegExpPrototypeExec(/^\stext\/plain\s(;\scharset=utf-?8\s)?$/i, mime) !== null) { return 'text'; }

		'module': kImplicitTypeAttribute,
		'wasm': kImplicitTypeAttribute, // It's unclear whether the HTML spec will require an type attribute or not for Wasm; see https://github.com/WebAssembly/esm-integration/issues/42

	const validType = getFormatType(format);
	const validType = formatTypeMap[format];

		if (!ArrayPrototypeIncludes(supportedTypeAttributes, type) &&
		!(type === 'text' && getOptionValue('--experimental-import-text'))) {

Uh oh!

Conversation

efekrskl commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Mar 17, 2026

Uh oh!

bakkot commented Mar 18, 2026

Uh oh!

efekrskl commented Mar 20, 2026

Uh oh!

codecov bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

GeoffreyBooth commented Mar 20, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

efekrskl Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GeoffreyBooth Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pdeveltere left a comment

Choose a reason for hiding this comment

Uh oh!

pdeveltere Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

efekrskl commented Mar 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bakkot commented Apr 2, 2026

Uh oh!

ShogunPanda commented Apr 3, 2026

Uh oh!

GeoffreyBooth commented Apr 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShogunPanda commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

efekrskl commented Mar 17, 2026 •

edited

Loading

codecov bot commented Mar 20, 2026 •

edited

Loading

efekrskl Mar 29, 2026 •

edited

Loading

GeoffreyBooth Mar 29, 2026 •

edited

Loading

pdeveltere Mar 26, 2026 •

edited

Loading