Esbuild Raw Plugin

An ESBuild/TSUP plugin to import files as raw text.
Ideal for scenarios like importing code files for documentation, interactive tools like react-live, or other text-based use cases.

Star this repository and share it with your friends.

Features

• Import any file (e.g., .js, .ts, .css, etc.) as raw text.
• Works seamlessly with ESBuild and TSUP.
• Perfect for documentation generators, live code editors, and similar tools.

Installation

Using npm:

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

Using yarn:

yarn add esbuild-raw-plugin --dev

Using pnpm:

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

Usage

ESBuild Configuration

Add the plugin to your ESBuild configuration:

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

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

TSUP Configuration

Add the plugin to your TSUP configuration:

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

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

IDE Setup for IntelliSense and Type Checking

Add the following to your declaration file. If you do not have one, create a declarations.d.ts file and add the following:

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

Importing Files as Raw Text

With the plugin enabled, you can import files as raw text directly:

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

console.log(myCode);
// Outputs the content of 'example.js' as a string.

Good News:

With the latest update, you no longer need to specify the file extension explicitly.

import myCode from "./example?raw";

This works seamlessly! Additionally, if you're exporting from files like index.tsx, index.jsx, etc., you can simplify imports. For example, if your file path is my-lib/index.ts, you can import the raw content like this:

import myCode from "./my-lib?raw";

Extension Options (Optional)

export interface RawPluginOptions {
  /**
   * Extensions to check in order if the file does not exist.
   * 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.
   */
  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[];
}

Supported File Types

You can use ?raw with any file type, including:

• .js, .ts, .jsx, .tsx
• .css, .scss
• .html
• .md
• and more!

Example Use Case

Live Code Preview with react-live

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

const App = () => (
  <LiveProvider code={exampleCode}>
    <LiveEditor />
    <LiveError />
    <LivePreview />
  </LiveProvider>
);

export default App;

Why Use esbuild-raw-plugin?

• Simplifies importing files as raw text for documentation and live previews.
• Seamlessly integrates with modern build tools like ESBuild and TSUP.
• Lightweight and easy to configure.

Keywords

esbuild, esbuild-plugin, tsup-plugin, raw-text-import, import-as-text, file-loader, react-live, documentation-tools, frontend-tooling

Contributing

Contributions are welcome!
Feel free to open issues or pull requests to improve the plugin.

Let me know if you'd like further tweaks! 🚀

License

This library is licensed under the MPL-2.0 open-source license.

Please enroll in our courses or sponsor our work.

with 💖 by Mayank Kumar Chaudhari