Package Exports

esbuild-raw-loader
esbuild-raw-loader/dist/index.js
esbuild-raw-loader/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (esbuild-raw-loader) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Esbuild Raw Plugin

npm bundle size

Lightweight ESBuild/TSUP plugin to import files as raw content — zero config required.

Import .ts, .js, .css, .scss, .md, .html, .docx, and more — perfect for documentation, live editors (react-live), markdown tooling, or template-driven workflows. Power users: Load .docx templates directly for mdast2docx.

Star this repository and share it with your dev circle.

🚀 Features

🔧 Supports ?raw, ?text, ?base64, ?dataurl, ?binary, and ?file query suffixes
🧠 Smart fallback to extensions like .ts, .tsx, index.[ext], etc.
🔍 Custom loader mapping (e.g., module.scss → text, png → dataurl)
⚡ Ultra-fast using regex-based native onLoad filter (Go-native perf)
🪶 Works seamlessly with both Tsup and ESBuild

📦 Installation

npm install esbuild-raw-plugin --save-dev

yarn add esbuild-raw-plugin --dev

pnpm add esbuild-raw-plugin --save-dev

🛠 Usage

➤ With ESBuild

import { build } from "esbuild";
import { raw } from "esbuild-raw-plugin";

build({
  entryPoints: ["src/index.js"],
  bundle: true,
  outfile: "out.js",
  plugins: [raw()],
});

➤ With TSUP

import { defineConfig } from "tsup";
import { raw } from "esbuild-raw-plugin";

export default defineConfig({
  entry: ["src/index.ts"],
  outDir: "dist",
  esbuildPlugins: [raw()],
});

🧠 TypeScript Support

Add this to your declarations.d.ts file:

declare module "*?raw" {
  const content: string;
  export default content;
}

For other suffixes (?base64, ?binary, etc.), add similar declarations if needed.

📥 Importing Raw Files

import content from "./example.js?raw";

console.log(content); // Entire file content as string or Buffer

✅ Simplified Imports

You don’t need to specify full filenames or extensions:

import code from "./utils?raw"; // Resolves to utils/index.ts, utils.js, etc.

Great for:

Library or folder-level imports
Auto-resolving .ts, .tsx, .css, .scss, etc.

⚙️ Plugin Options

export interface RawPluginOptions {
  ext?: string[];
  loader?: "text" | "base64" | "dataurl" | "file" | "binary" | "default";
  customLoaders?: Record<string, "text" | "base64" | "dataurl" | "file" | "binary" | "default">;
  name?: string;
}

🔧 Option Details

ext: Extensions to resolve if the file or folder is missing. Defaults to common types like ts, tsx, module.css, etc.
loader: Default loader if no ?query is specified. Usually "text".

customLoaders: Per-extension loader mapping. Example:

{
  "module.scss": "text",
  "png": "dataurl",
  "docx": "file"
}

name: Optional plugin name override for debugging or deduplication.

🧪 Supported Query Loaders

Import with query-based syntax:

import doc from "./readme.md?text";
import logo from "./logo.png?base64";
import wasm from "./core.wasm?binary";

Query Suffix	Description
`?raw`	Uses the default loader (options.loader ?? "text")
`?text`	Loads file as UTF-8 text
`?base64`	Returns base64 string
`?dataurl`	Returns full data URL
`?file`	Emits file to output dir
`?binary`	Returns raw `Buffer`

🧬 Use Case: Live Code Preview

import { LiveProvider, LiveEditor, LiveError, LivePreview } from "react-live";
import exampleCode from "./example.js?raw";

export default function LiveDemo() {
  return (
    <LiveProvider code={exampleCode}>
      <LiveEditor />
      <LiveError />
      <LivePreview />
    </LiveProvider>
  );
}

🔍 Why Choose `esbuild-raw-plugin`?

✅ Works out of the box — no config needed
📁 Handles smart file resolution
💬 Excellent developer experience
🧩 Supports both query-based and extension-based mappings
🧪 Stable, fast, and production-tested

🛠 Contributing

PRs and ideas welcome! Open an issue or submit a pull request to help improve the plugin.

Alt

🧾 License

Licensed under the MPL-2.0 open-source license.

Please consider sponsoring or joining a course to support this work.

with 💖 by Mayank Kumar Chaudhari

esbuild-raw-loader