docs(changeset): fix: backward compatibility - add support for and deprecate the deprecated textExtensions field in raw plugin options

Author: mayank1513

.changeset/new-schools-accept.md

@@ -0,0 +1,5 @@
+---
+"esbuild-raw-plugin": patch
+---
+
+fix: backward compatibility - add support for and deprecate the deprecated textExtensions field in raw plugin options

lib/__tests__/index.test.ts

@@ -100,6 +100,7 @@ describe("Raw plugin", () => {
     const plugin = raw({ name: "custom-plugin-name" });
     expect(plugin.name).toBe("custom-plugin-name");
   });
+
   test("custom loader", async ({ expect }) => {
     await esbuild.build({
       ...buildOptions,
@@ -111,4 +112,17 @@ describe("Raw plugin", () => {
     const generatedCodeContent = (await import("./dist/test-loader.js")).getText();
     expect(generatedCodeContent).toBe(fileContent.toString("base64"));
   });
+
+  test("deprecated textExtensions", async ({ expect }) => {
+    await esbuild.build({
+      ...buildOptions,
+      plugins: [raw({ textExtensions: ["md"] })],
+      entryPoints: [path.resolve(__dirname, "test3.ts")],
+      outdir: "__tests__/dist3",
+    });
+    const fileContent = fs.readFileSync(path.resolve(__dirname, "test.md"), "utf-8");
+    // @ts-ignore
+    const generatedCodeContent = (await import("./dist3/test3.js")).getText();
+    expect(generatedCodeContent).toBe(fileContent);
+  });
 });

lib/src/index.ts

@@ -40,6 +40,17 @@ export interface RawPluginOptions {
    * Plugin name override (for debugging, deduplication, etc.)
    */
   name?: string;
+
+  /**
+   * @deprecated Use `customLoaders` instead.
+   * Previously used to specify extensions to treat as text.
+   *
+   * Example replacement:
+   * ```ts
+   * customLoaders: { "module.scss": "text", "md": "text" }
+   * ```
+   */
+  textExtensions?: string[];
 }
 
 /**
@@ -112,10 +123,14 @@ export const raw = (options?: RawPluginOptions): Plugin => ({
       return { contents: buffer, loader };
     });
 
-    if (options?.customLoaders) {
-      const customLoaderKeys = Object.keys(options.customLoaders).sort(
-        (a, b) => b.length - a.length,
-      );
+    if (options?.customLoaders || options?.textExtensions) {
+      const customLoaderKeys = [
+        ...new Set([
+          ...Object.keys(options.customLoaders ?? {}),
+          ...(options?.textExtensions ?? []),
+        ]),
+      ].sort((a, b) => b.length - a.length);
+
       const pattern = new RegExp(
         `\\.(${customLoaderKeys
           .map(e => e.replace(/^\./, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
@@ -125,7 +140,10 @@ export const raw = (options?: RawPluginOptions): Plugin => ({
       build.onLoad({ filter: pattern }, args => {
         const path = args.path;
         const loaderKey = customLoaderKeys.find(suffix => path.endsWith(suffix));
-        const loader = options.customLoaders?.[loaderKey ?? ""];
+        let loader = options.customLoaders?.[loaderKey ?? ""];
+
+        if (!loader && options?.textExtensions?.includes(loaderKey ?? "")) loader = "text";
+
         if (!loader) return;
 
         const buffer = fs.readFileSync(path);