esm: add --experimental-import-text flag

efekrskl · richardlau · commit b373202efc89 · 2026-07-03T16:04:32.000Z
Signed-off-by: Efe Karasakal <hi@efe.dev> PR-URL: #62300 Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: Ilyas Shabi <ilyasshabi94@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1255,6 +1255,18 @@ passing a second `parentURL` argument for contextual resolution.
 
 Previously gated the entire `import.meta.resolve` feature.
 
+### `--experimental-import-text`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+Enable experimental support for importing modules with
+`with { type: 'text' }`.
+
 ### `--experimental-inspector-network-resource`
 
 <!-- YAML
@@ -3781,6 +3793,7 @@ one is included in the list below.
 * `--experimental-eventsource`
 * `--experimental-ffi`
 * `--experimental-import-meta-resolve`
+* `--experimental-import-text`
 * `--experimental-json-modules`
 * `--experimental-loader`
 * `--experimental-modules`
diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -294,8 +294,10 @@ Node.js only supports the `type` attribute, for which it supports the following
 | Attribute `type` | Needed for       |
 | ---------------- | ---------------- |
 | `'json'`         | [JSON modules][] |
+| `'text'`         | [Text modules][] |
 
 The `type: 'json'` attribute is mandatory when importing JSON modules.
+The `type: 'text'` attribute is mandatory when importing text modules.
 
 ## Built-in modules
 
@@ -707,6 +709,23 @@ exports. A cache entry is created in the CommonJS cache to avoid duplication.
 The same object is returned in CommonJS if the JSON module has already been
 imported from the same path.
 
+## Text modules
+
+> Stability: 1.0 - Early development
+
+Text modules are available behind the `--experimental-import-text` flag.
+
+Text files can be referenced by `import`:
+
+```js
+import message from './message.txt' with { type: 'text' };
+```
+
+The `with { type: 'text' }` syntax is mandatory; see [Import Attributes][].
+
+The imported text only exposes a `default` export whose value is the module
+source as a string.
+
 <i id="esm_experimental_wasm_modules"></i>
 
 ## Wasm modules
@@ -1313,6 +1332,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
 [Package maps]: packages.md#package-maps
 [Source Phase Imports]: https://github.com/tc39/proposal-source-phase-imports
 [Terminology]: #terminology
+[Text modules]: #text-modules
 [URL]: https://url.spec.whatwg.org/
 [WebAssembly JS String Builtins Proposal]: https://github.com/WebAssembly/js-string-builtins
 [`"exports"`]: packages.md#exports
diff --git a/lib/internal/modules/esm/assert.js b/lib/internal/modules/esm/assert.js
@@ -8,6 +8,7 @@ const {
   ObjectValues,
 } = primordials;
 const { validateString } = require('internal/validators');
+const { getOptionValue } = require('internal/options');
 
 const {
   ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE,
@@ -29,8 +30,13 @@ const formatTypeMap = {
   'commonjs': kImplicitTypeAttribute,
   'json': 'json',
   '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
 };
+// 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
+
 
 /**
  * The HTML spec disallows the default type to be explicitly specified
@@ -42,7 +48,6 @@ const supportedTypeAttributes = ArrayPrototypeFilter(
   ObjectValues(formatTypeMap),
   (type) => type !== kImplicitTypeAttribute);
 
-
 /**
  * Test a module's import attributes.
  * @param {string} url The URL of the imported module, for error reporting.
@@ -62,6 +67,12 @@ function validateAttributes(url, format,
   }
   const validType = formatTypeMap[format];
 
+  if (validType !== undefined &&
+    importAttributes.type === 'text' &&
+    !getOptionValue('--experimental-import-text')) {
+    throw new ERR_IMPORT_ATTRIBUTE_UNSUPPORTED('type', importAttributes.type, url);
+  }
+
   switch (validType) {
     case undefined:
       // Ignore attributes for module formats we don't recognize, to allow new
diff --git a/lib/internal/modules/esm/get_format.js b/lib/internal/modules/esm/get_format.js
@@ -47,6 +47,13 @@ function mimeToFormat(mime) {
   ) { return 'module'; }
   if (mime === 'application/json') { return 'json'; }
   if (mime === 'application/wasm') { return 'wasm'; }
+  if (
+    getOptionValue('--experimental-import-text') &&
+    RegExpPrototypeExec(
+      /^\s*text\/plain\s*(;\s*charset=utf-?8\s*)?$/i,
+      mime,
+    ) !== null
+  ) { return 'text'; }
   return null;
 }
 
@@ -236,12 +243,22 @@ function getFileProtocolModuleFormat(url, context = { __proto__: null }, ignoreE
   throw new ERR_UNKNOWN_FILE_EXTENSION(ext, filepath);
 }
 
+// If the caller explicitly requests text format via import attributes, honor it regardless of file extension.
+function isExperimentalTextImport(importAttributes) {
+  return getOptionValue('--experimental-import-text') &&
+    importAttributes?.type === 'text';
+}
+
 /**
  * @param {URL} url
- * @param {{parentURL: string}} context
+ * @param {{parentURL: string, importAttributes?: Record<string, string>}} context
  * @returns {Promise<string> | string | undefined} only works when enabled
  */
 function defaultGetFormatWithoutErrors(url, context) {
+  if (isExperimentalTextImport(context?.importAttributes)) {
+    return 'text';
+  }
+
   const protocol = url.protocol;
   if (!ObjectPrototypeHasOwnProperty(protocolHandlers, protocol)) {
     return null;
@@ -251,10 +268,14 @@ function defaultGetFormatWithoutErrors(url, context) {
 
 /**
  * @param {URL} url
- * @param {{parentURL: string}} context
+ * @param {{parentURL: string, importAttributes?: Record<string, string>}} context
  * @returns {Promise<string> | string | undefined} only works when enabled
  */
 function defaultGetFormat(url, context) {
+  if (isExperimentalTextImport(context?.importAttributes)) {
+    return 'text';
+  }
+
   const protocol = url.protocol;
   if (!ObjectPrototypeHasOwnProperty(protocolHandlers, protocol)) {
     return null;
diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
@@ -99,7 +99,7 @@ const { defaultLoadSync, throwUnknownModuleFormat } = require('internal/modules/
  */
 
 /**
- * @typedef {'builtin'|'commonjs'|'json'|'module'|'wasm'} ModuleFormat
+ * @typedef {'builtin'|'commonjs'|'json'|'module'|'text'|'wasm'} ModuleFormat
  */
 
 /**
diff --git a/lib/internal/modules/esm/translators.js b/lib/internal/modules/esm/translators.js
@@ -681,3 +681,14 @@ translators.set('module-typescript', function(url, translateContext, parentURL)
   translateContext.source = stripTypeScriptModuleTypes(stringify(source), url);
   return FunctionPrototypeCall(translators.get('module'), this, url, translateContext, parentURL);
 });
+
+// Strategy for loading source as text.
+translators.set('text', function textStrategy(url, translateContext) {
+  emitExperimentalWarning('Text import');
+  let { source } = translateContext;
+  assertBufferSource(source, true, 'load');
+  source = stringify(source);
+  return new ModuleWrap(url, undefined, ['default'], function() {
+    this.setExport('default', source);
+  });
+});
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -647,6 +647,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddAlias("--loader", "--experimental-loader");
   AddOption("--experimental-modules", "", NoOp{}, kAllowedInEnvvar);
   AddOption("--experimental-wasm-modules", "", NoOp{}, kAllowedInEnvvar);
+  AddOption("--experimental-import-text",
+            "experimental support for importing source as text with import "
+            "attributes",
+            &EnvironmentOptions::experimental_import_text,
+            kAllowedInEnvvar);
   AddOption("--experimental-import-meta-resolve",
             "experimental ES Module import.meta.resolve() parentURL support",
             &EnvironmentOptions::experimental_import_meta_resolve,
diff --git a/src/node_options.h b/src/node_options.h
@@ -138,6 +138,7 @@ class EnvironmentOptions : public Options {
   std::string localstorage_file;
   bool experimental_global_navigator = true;
   bool experimental_global_web_crypto = true;
+  bool experimental_import_text = EXPERIMENTALS_DEFAULT_VALUE;
   bool experimental_import_meta_resolve = EXPERIMENTALS_DEFAULT_VALUE;
   std::string input_type;  // Value of --input-type
   bool entry_is_url = false;
diff --git a/test/es-module/test-esm-import-attributes-errors.js b/test/es-module/test-esm-import-attributes-errors.js
@@ -26,6 +26,11 @@ async function test() {
     { code: 'ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE' }
   );
 
+  await assert.rejects(
+    import(jsModuleDataUrl, { with: { type: 'text' } }),
+    { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }
+  );
+
   await assert.rejects(
     import(jsModuleDataUrl, { with: { type: 'json', other: 'unsupported' } }),
     { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }
diff --git a/test/es-module/test-esm-import-attributes-errors.mjs b/test/es-module/test-esm-import-attributes-errors.mjs
@@ -21,6 +21,11 @@ await assert.rejects(
   { code: 'ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE' }
 );
 
+await assert.rejects(
+  import(jsModuleDataUrl, { with: { type: 'text' } }),
+  { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }
+);
+
 await assert.rejects(
   import(jsModuleDataUrl, { with: { type: 'json', other: 'unsupported' } }),
   { code: 'ERR_IMPORT_ATTRIBUTE_UNSUPPORTED' }
diff --git a/test/es-module/test-esm-import-attributes-validation-text.js b/test/es-module/test-esm-import-attributes-validation-text.js
@@ -0,0 +1,19 @@
+// Flags: --expose-internals --experimental-import-text
+'use strict';
+require('../common');
+
+const assert = require('assert');
+
+const { validateAttributes } = require('internal/modules/esm/assert');
+
+const url = 'test://';
+
+assert.ok(validateAttributes(url, 'text', { type: 'text' }));
+
+assert.throws(() => validateAttributes(url, 'text', {}), {
+  code: 'ERR_IMPORT_ATTRIBUTE_MISSING',
+});
+
+assert.throws(() => validateAttributes(url, 'module', { type: 'text' }), {
+  code: 'ERR_IMPORT_ATTRIBUTE_TYPE_INCOMPATIBLE',
+});
diff --git a/test/es-module/test-esm-import-text-disabled.mjs b/test/es-module/test-esm-import-text-disabled.mjs
@@ -0,0 +1,12 @@
+import '../common/index.mjs';
+import assert from 'assert';
+
+await assert.rejects(
+  import('../fixtures/file-to-read-without-bom.txt', { with: { type: 'text' } }),
+  { code: 'ERR_UNKNOWN_FILE_EXTENSION' },
+);
+
+await assert.rejects(
+  import('data:text/plain,hello%20world', { with: { type: 'text' } }),
+  { code: 'ERR_UNKNOWN_MODULE_FORMAT' },
+);
diff --git a/test/es-module/test-esm-import-text.mjs b/test/es-module/test-esm-import-text.mjs
@@ -0,0 +1,51 @@
+// Flags: --experimental-import-text
+import '../common/index.mjs';
+import assert from 'assert';
+
+import staticText from '../fixtures/file-to-read-without-bom.txt' with { type: 'text' };
+import staticTextWithBOM from '../fixtures/file-to-read-with-bom.txt' with { type: 'text' };
+
+const expectedText = 'abc\ndef\nghi\n';
+
+assert.strictEqual(staticText, expectedText);
+assert.strictEqual(staticTextWithBOM, expectedText);
+
+const dynamicText = await import('../fixtures/file-to-read-without-bom.txt', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dynamicText.default, expectedText);
+
+const dataText = await import('data:text/plain,hello%20world', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dataText.default, 'hello world');
+
+const dataJsAsText = await import('data:text/javascript,export{}', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dataJsAsText.default, 'export{}');
+
+const dataInvalidUtf8 = await import('data:text/plain,%66%6f%80%6f', {
+  with: { type: 'text' },
+});
+assert.strictEqual(dataInvalidUtf8.default, 'fo\ufffdo');
+
+const jsAsText = await import('../fixtures/syntax/bad_syntax.js', {
+  with: { type: 'text' },
+});
+assert.match(jsAsText.default, /^var foo bar;/);
+
+const jsonAsText = await import('../fixtures/invalid.json', {
+  with: { type: 'text' },
+});
+assert.match(jsonAsText.default, /"im broken"/);
+
+await assert.rejects(
+  import('data:text/plain,hello%20world'),
+  { code: 'ERR_IMPORT_ATTRIBUTE_MISSING' },
+);
+
+await assert.rejects(
+  import('../fixtures/file-to-read-without-bom.txt'),
+  { code: 'ERR_UNKNOWN_FILE_EXTENSION' },
+);
