Extend library to add cutom loader, text extensions and update test cases

Author: mayank1513

README.md

@@ -76,7 +76,7 @@ export default defineConfig({
 
 ## IDE Setup for IntelliSense and Type Checking
 
-Add following to your declaration file. If you do not have one, create `declarations.d.ts` file and add following.
+Add the following to your declaration file. If you do not have one, create a `declarations.d.ts` file and add the following:
 
 ```typescript
 declare module "*?raw" {
@@ -122,6 +122,17 @@ export interface RawPluginOptions {
    * You can provide your own extensions to optimize build performance or extend the list based on your use case.
    */
   ext?: string[];
+
+  /**
+   * Custom loader for file processing.
+   * @defaultValue "text"
+   */
+  loader?: "text" | "base64" | "dataurl" | "file" | "binary" | "default";
+
+  /**
+   * Extensions to be treated as text files.
+   */
+  textExtensions?: string[];
 }
 ```
 

lib/__tests__/declarations.d.ts

@@ -1 +1,2 @@
 declare module "*?raw";
+declare module "*.md";

lib/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { beforeAll, describe, test } from "vitest";
+import { describe, test } from "vitest";
 import esbuild, { BuildOptions } from "esbuild";
 import path from "node:path";
 import { raw } from "../src";
@@ -16,7 +16,7 @@ const buildOptions: BuildOptions = {
   plugins: [raw()],
 };
 
-describe("WebGL plugins", () => {
+describe("Raw plugin", () => {
   test("test raw import", async ({ expect }) => {
     await esbuild.build(buildOptions);
     const fileContent = fs.readFileSync(path.resolve(__dirname, "../src/index.ts"), "utf-8");
@@ -42,4 +42,29 @@ describe("WebGL plugins", () => {
     }
     expect(didThrow).toBe(true);
   });
+
+  test("textExtensions", async ({ expect }) => {
+    await esbuild.build({
+      ...buildOptions,
+      plugins: [raw({ textExtensions: [".md"] })],
+      entryPoints: [path.resolve(__dirname, "test3.ts")],
+    });
+
+    const fileContent = fs.readFileSync(path.resolve(__dirname, "test.md"), "utf-8");
+    // @ts-ignore
+    const generatedCodeContent = (await import("./dist/test3.js")).getText();
+    expect(fileContent).toBe(generatedCodeContent);
+  });
+
+  test("custom loader", async ({ expect }) => {
+    await esbuild.build({
+      ...buildOptions,
+      entryPoints: [path.resolve(__dirname, "test-loader.ts")],
+      plugins: [raw({ loader: "base64" })],
+    });
+    const fileContent = fs.readFileSync(path.resolve(__dirname, "../src/index.ts"), "utf-8");
+    // @ts-ignore
+    const generatedCodeContent = (await import("./dist/test-loader.js")).getText();
+    expect(fileContent).toBe(atob(generatedCodeContent));
+  });
 });

lib/__tests__/test-loader.ts

@@ -0,0 +1,3 @@
+import text from "../src/index.ts?raw";
+
+export const getText = () => text;

lib/__tests__/test.md

@@ -0,0 +1 @@
+I am not supported by default

lib/__tests__/test3.ts

@@ -0,0 +1,5 @@
+// test cutom extension
+
+import text from "./test.md";
+
+export const getText = () => text;

lib/src/index.ts

@@ -4,60 +4,95 @@ import path from "node:path";
 
 export interface RawPluginOptions {
   /**
-   * Extensions to check in order if the file does not exist.
+   * File extensions to check in order of priority if the specified file is missing.
    * If it's a directory, the plugin will look for `dir/index.[ext]`.
-   * @defaultValue ["tsx", "ts", "jsx", "js", "mjs", "mts", "module.css", "module.scss", "css", "scss"]
-   *
-   * You can provide your own extensions to optimize build performance or extend the list based on your use case.
+   * @defaultValue ["ts", "tsx", "js", "jsx", "mjs", "mts", "module.css", "module.scss", "css", "scss"]
    */
   ext?: string[];
+
+  /**
+   * Custom loader for file processing.
+   * @defaultValue "text"
+   */
+  loader?: "text" | "base64" | "dataurl" | "file" | "binary" | "default";
+
+  /**
+   * Extensions to be treated as text files.
+   */
+  textExtensions?: string[];
 }
 
-/** Plugin to load `.glsl` files as minified strings */
+/**
+ * ESBuild plugin to enable raw file imports.
+ *
+ * This plugin allows importing files with a `?raw` suffix,
+ * treating them as raw text content. It supports resolving file
+ * extensions in order of priority and handling custom loaders.
+ */
 export const raw: (options?: RawPluginOptions) => Plugin = options => ({
-  /** generate randmo name to avoid collision among the plugins */
-  name: `raw-${(Date.now() * Math.random()).toString(36).slice(0, 8)}`,
+  name: `raw-${Math.random().toString(36).slice(2, 10)}`,
   setup(build: PluginBuild) {
     const ext = options?.ext ?? [
-      "tsx",
       "ts",
-      "jsx",
+      "tsx",
       "js",
+      "jsx",
       "mjs",
       "mts",
       "module.css",
       "module.scss",
       "css",
       "scss",
     ];
-    build.onResolve({ filter: /\?raw$/ }, args => {
-      const filePath = args.path;
-      return {
-        path: filePath,
-        pluginData: path.resolve(args.resolveDir, filePath).replace(/\?raw$/, ""),
-        namespace: "raw",
-      };
-    });
+
+    build.onResolve({ filter: /\?raw$/ }, args => ({
+      path: args.path,
+      pluginData: path.resolve(args.resolveDir, args.path).replace(/\?raw$/, ""),
+      namespace: "raw",
+    }));
+
     build.onLoad({ filter: /\?raw$/, namespace: "raw" }, args => {
       let filePath = args.pluginData;
-      if (fs.existsSync(filePath) && fs.lstatSync(filePath).isDirectory())
-        filePath += path.sep + "index";
-      if (!fs.existsSync(filePath))
-        for (const e of ext)
-          if (fs.existsSync(filePath + "." + e)) {
-            filePath += "." + e;
+      if (options?.loader && options.loader !== "text") {
+        return { contents: fs.readFileSync(filePath, "utf8"), loader: options.loader };
+      }
+
+      if (fs.existsSync(filePath) && fs.lstatSync(filePath).isDirectory()) {
+        filePath = path.join(filePath, "index");
+      }
+
+      if (!fs.existsSync(filePath)) {
+        for (const e of ext) {
+          if (fs.existsSync(`${filePath}.${e}`)) {
+            filePath += `.${e}`;
             break;
           }
-      if (!fs.existsSync(filePath))
+        }
+      }
+
+      if (!fs.existsSync(filePath)) {
         throw new Error(
           /* v8 ignore next */
-          `File not found: ${args.pluginData}\nWe checked for following extensions: ${ext.join(", ")}. You can customise by passing {ext: [...]} to raw({ext:[...]})`,
+          `File not found: ${args.pluginData}\nChecked extensions: ${ext.join(", ")}. You can customize this using { ext: [...] }.`,
           /* v8 ignore next */
         );
-      return {
-        contents: fs.readFileSync(filePath, "utf8"),
-        loader: "text",
-      };
+      }
+
+      return { contents: fs.readFileSync(filePath, "utf8"), loader: "text" };
     });
+
+    if (options?.textExtensions?.length) {
+      build.onLoad(
+        {
+          filter: new RegExp(
+            `\.(${options.textExtensions.map(e => e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})$`,
+          ),
+        },
+        args => ({
+          contents: fs.readFileSync(args.path, "utf8"),
+          loader: "text",
+        }),
+      );
+    }
   },
 });