@babel/plugin-proposal-text-modules

Transforms import ... with { type: "text" } declarations to platform-specific API to read the imported file and decode it as UTF-8 text.

The transformation applied by this plugin depends on your top-level targets to detect whether the generated code should be compatible with Node.js, browsers, or both. When targeting Node.js, the generated code will also change depending on whether you are compiling modules to CommonJS or not.

caution

This plugin only transforms static import declarations, not dynamic import() calls, and when compiling modules it only supports CommonJS output.

Example

input.js

import banner from "./banner.txt" with { type: "text" };

will be transformed to

Browsers

output.js

const banner = await fetch(import.meta.resolve("./banner.txt")).then(r => r.text());

Node.js (ESM)

output.mjs

import { readFileSync as _readFileSync } from "fs";
const banner = String(_readFileSync(new URL(import.meta.resolve("./banner.txt"))));

Node.js (CommonJS)

output.cjs

"use strict";

const banner = String(require("fs").readFileSync(require.resolve("./banner.txt")));

Browsers and Node.js (ESM)

output.js

const banner = await (
  typeof process === "object" && process.versions?.node
    ? import("fs").then(fs => fs.promises.readFile(new URL(import.meta.resolve("./banner.txt")))).then(String)
    : fetch(import.meta.resolve("./banner.txt")).then(r => r.text())
);

Namespace imports are also supported, and are compiled to an object with a single default property:

input.js

import * as ns from "./banner.txt" with { type: "text" };

Named imports are not valid for text modules, and will cause a compilation error.

Installation

npm

npm install --save-dev @babel/plugin-proposal-text-modules

Yarn

yarn add --dev @babel/plugin-proposal-text-modules

pnpm

pnpm add --save-dev @babel/plugin-proposal-text-modules

Bun

bun add --dev @babel/plugin-proposal-text-modules

Usage

With a configuration file (Recommended)

babel.config.json

{
  "plugins": ["@babel/plugin-proposal-text-modules"]
}

Via CLI

Shell

babel --plugins=@babel/plugin-proposal-text-modules script.js

Via Node API

JavaScript

require("@babel/core").transformSync("code", {
  plugins: ["@babel/plugin-proposal-text-modules"],
});

References

• Proposal: Import Text