{"id":23158579,"url":"https://github.com/react18-tools/esbuild-raw-plugin","last_synced_at":"2025-09-20T10:13:00.249Z","repository":{"id":268396625,"uuid":"904158477","full_name":"react18-tools/esbuild-raw-plugin","owner":"react18-tools","description":"ESBuild/TSUP plugin to import files as raw text — perfect for documentation and `react-live`.","archived":false,"fork":false,"pushed_at":"2025-09-17T08:24:40.000Z","size":2569,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T10:25:37.528Z","etag":null,"topics":["code-snippets","esbuild","esbuild-plugin","javascript","live-editor","nodejs","raw-import","react-live","reactjs","tsup","tsup-plugin","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/react18-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["react18-tools","mayank1513"],"polar":"mayank1513","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://pages.razorpay.com/mayank1513"]}},"created_at":"2024-12-16T11:07:39.000Z","updated_at":"2025-09-17T08:24:45.000Z","dependencies_parsed_at":"2024-12-16T14:31:53.215Z","dependency_job_id":"af888b6f-0e8d-4af8-93f9-143a512be31f","html_url":"https://github.com/react18-tools/esbuild-raw-plugin","commit_stats":null,"previous_names":["react18-tools/esbuild-raw-plugin"],"tags_count":6,"template":false,"template_full_name":"react18-tools/turborepo-template","purl":"pkg:github/react18-tools/esbuild-raw-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react18-tools%2Fesbuild-raw-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react18-tools%2Fesbuild-raw-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react18-tools%2Fesbuild-raw-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react18-tools%2Fesbuild-raw-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/react18-tools","download_url":"https://codeload.github.com/react18-tools/esbuild-raw-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/react18-tools%2Fesbuild-raw-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275976109,"owners_count":25563046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-snippets","esbuild","esbuild-plugin","javascript","live-editor","nodejs","raw-import","react-live","reactjs","tsup","tsup-plugin","typescript"],"created_at":"2024-12-17T22:20:23.791Z","updated_at":"2025-09-20T10:13:00.200Z","avatar_url":"https://github.com/react18-tools.png","language":"JavaScript","funding_links":["https://github.com/sponsors/react18-tools","https://github.com/sponsors/mayank1513","https://polar.sh/mayank1513","https://pages.razorpay.com/mayank1513"],"categories":[],"sub_categories":[],"readme":"# Esbuild Raw Plugin \u003cimg src=\"https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png\" style=\"height: 40px\"/\u003e\n\n[![test](https://github.com/react18-tools/esbuild-raw-plugin/actions/workflows/test.yml/badge.svg)](https://github.com/react18-tools/esbuild-raw-plugin/actions/workflows/test.yml)\n[![Maintainability](https://api.codeclimate.com/v1/badges/aa896ec14c570f3bb274/maintainability)](https://codeclimate.com/github/react18-tools/esbuild-raw-plugin/maintainability)\n[![codecov](https://codecov.io/gh/react18-tools/esbuild-raw-plugin/graph/badge.svg)](https://codecov.io/gh/react18-tools/esbuild-raw-plugin)\n[![Version](https://img.shields.io/npm/v/esbuild-raw-plugin.svg?colorB=green)](https://www.npmjs.com/package/esbuild-raw-plugin)\n[![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/esbuild-raw-plugin.svg)](https://www.npmjs.com/package/esbuild-raw-plugin)\n![npm bundle size](https://img.shields.io/bundlephobia/minzip/esbuild-raw-plugin)\n[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/from-referrer/)\n\n**Lightweight ESBuild/TSUP plugin to import files as raw content — zero config required.**\n\n\u003e 🔌Import `.ts`, `.js`, `.css`, `.scss`, `.md`, `.html`, `.docx`, and more — perfect for documentation, live editors (`react-live`), markdown tooling, or template-driven workflows.\n\u003e ⚡️Power users: Load `.docx` templates directly for [mdast2docx](https://github.com/md2docx/mdast2docx).\n\n\u003e \u003cimg src=\"https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png\" style=\"height: 20px\"/\u003e Star [this repository](https://github.com/react18-tools/esbuild-raw-plugin) and share it with your dev circle.\n\n---\n\n## 🚀 Features\n\n\u003e 🔥 Import any file as raw content with zero config in ESBuild or TSUP — text, base64, binary, docx templates \u0026 more!\\\n\u003e ⚡️ Fast, smart, and extensible → `esbuild-raw-plugin`\n\n- 🔧 Supports `?raw`, `?text`, `?base64`, `?dataurl`, `?binary`, and `?file` query suffixes\n- 🧠 Smart fallback to extensions like `.ts`, `.tsx`, `index.[ext]`, etc.\n- 🔍 Custom loader mapping (e.g., `module.scss` → `text`, `png` → `dataurl`)\n- ⚡ Ultra-fast using regex-based native `onLoad` filter (Go-native perf)\n- 🪶 Works seamlessly with both [Tsup](https://tsup.egoist.dev/) and [ESBuild](https://esbuild.github.io/)\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install esbuild-raw-plugin --save-dev\n```\n\n_or_\n\n```bash\nyarn add esbuild-raw-plugin --dev\n```\n\n_or_\n\n```bash\npnpm add esbuild-raw-plugin --save-dev\n```\n\n---\n\n## 🛠 Usage\n\n### ➤ With ESBuild\n\n```ts\nimport { build } from \"esbuild\";\nimport { raw } from \"esbuild-raw-plugin\";\n\nbuild({\n  entryPoints: [\"src/index.js\"],\n  bundle: true,\n  outfile: \"out.js\",\n  plugins: [raw()],\n});\n```\n\n### ➤ With TSUP\n\n```ts\nimport { defineConfig } from \"tsup\";\nimport { raw } from \"esbuild-raw-plugin\";\n\nexport default defineConfig({\n  entry: [\"src/index.ts\"],\n  outDir: \"dist\",\n  esbuildPlugins: [raw()],\n});\n```\n\n---\n\n## 🧠 TypeScript Support\n\nAdd this to your `declarations.d.ts` file:\n\n```ts\ndeclare module \"*?raw\" {\n  const content: string;\n  export default content;\n}\n```\n\n\u003e For other suffixes (`?base64`, `?binary`, etc.), add similar declarations if needed.\n\n---\n\n## 📥 Importing Raw Files\n\n```ts\nimport content from \"./example.js?raw\";\n\nconsole.log(content); // Entire file content as string or Buffer\n```\n\n### ✅ Simplified Imports\n\nYou don’t need to specify full filenames or extensions:\n\n```ts\nimport code from \"./utils?raw\"; // Resolves to utils/index.ts, utils.js, etc.\n```\n\nGreat for:\n\n- Library or folder-level imports\n- Auto-resolving `.ts`, `.tsx`, `.css`, `.scss`, etc.\n\n---\n\n## ⚙️ Plugin Options\n\n```ts\nexport interface RawPluginOptions {\n  ext?: string[];\n  loader?: \"text\" | \"base64\" | \"dataurl\" | \"file\" | \"binary\" | \"default\";\n  customLoaders?: Record\u003cstring, \"text\" | \"base64\" | \"dataurl\" | \"file\" | \"binary\" | \"default\"\u003e;\n  name?: string;\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔧 Option Details\u003c/strong\u003e\u003c/summary\u003e\n\n- `ext`: Extensions to resolve if the file or folder is missing. Defaults to common types like `ts`, `tsx`, `module.css`, etc.\n- `loader`: Default loader if no `?query` is specified. Usually `\"text\"`.\n- `customLoaders`: Per-extension loader mapping. Example:\n\n  ```ts\n  {\n    \"module.scss\": \"text\",\n    \"png\": \"dataurl\",\n    \"docx\": \"file\"\n  }\n  ```\n\n- `name`: Optional plugin name override for debugging or deduplication.\n\n\u003c/details\u003e\n\n---\n\n## 🧪 Supported Query Loaders\n\nImport with query-based syntax:\n\n```ts\nimport doc from \"./readme.md?text\";\nimport logo from \"./logo.png?base64\";\nimport wasm from \"./core.wasm?binary\";\n```\n\n| Query Suffix | Description                                        |\n| ------------ | -------------------------------------------------- |\n| `?raw`       | Uses the default loader (options.loader ?? \"text\") |\n| `?text`      | Loads file as UTF-8 text                           |\n| `?base64`    | Returns base64 string                              |\n| `?dataurl`   | Returns full data URL                              |\n| `?file`      | Emits file to output dir                           |\n| `?binary`    | Returns raw `Buffer`                               |\n\n---\n\n## 🧬 Use Case: Live Code Preview\n\n```tsx\nimport { LiveProvider, LiveEditor, LiveError, LivePreview } from \"react-live\";\nimport exampleCode from \"./example.js?raw\";\n\nexport default function LiveDemo() {\n  return (\n    \u003cLiveProvider code={exampleCode}\u003e\n      \u003cLiveEditor /\u003e\n      \u003cLiveError /\u003e\n      \u003cLivePreview /\u003e\n    \u003c/LiveProvider\u003e\n  );\n}\n```\n\n---\n\n## 🔍 Why Choose `esbuild-raw-plugin`?\n\n- ✅ Works out of the box — no config needed\n- 📁 Handles smart file resolution\n- 💬 Excellent developer experience\n- 🧩 Supports both query-based and extension-based mappings\n- 🧪 Stable, fast, and production-tested\n\n---\n\n## 🛠 Contributing\n\nPRs and ideas welcome!\nOpen an issue or submit a pull request to help improve the plugin.\n\n![Alt](https://repobeats.axiom.co/api/embed/1ae166ef108b33b36ceaa60be208a5dafce25c5c.svg \"Repobeats analytics image\")\n\n---\n\n## 🧾 License\n\nLicensed under the **MPL-2.0** open-source license.\n\n\u003e \u003cimg src=\"https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png\" style=\"height: 20px\"/\u003e Please consider [sponsoring](https://github.com/sponsors/mayank1513) or [joining a course](https://mayank-chaudhari.vercel.app/courses) to support this work.\n\n---\n\n\u003cp align=\"center\" style=\"text-align:center\"\u003ewith 💖 by \u003ca href=\"https://mayank-chaudhari.vercel.app\" target=\"_blank\"\u003eMayank Kumar Chaudhari\u003c/a\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freact18-tools%2Fesbuild-raw-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freact18-tools%2Fesbuild-raw-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freact18-tools%2Fesbuild-raw-plugin/lists"}