{"id":25437,"library":"esbuild-raw-plugin","title":"esbuild-raw-plugin","description":"An ESBuild and TSUP plugin that allows importing files as raw text, base64, binary, or data URLs with zero configuration. Version 0.3.1 is the latest stable release, with recent releases including backward-compatible fixes and binary loader improvements. Key differentiators: supports query suffixes like ?raw, ?text, ?base64, ?binary, ?dataurl, ?file; smart fallback extension resolution; custom loader mapping; regex-based native onLoad filter for performance; works with both ESBuild and TSUP. Developed under react18-tools, it is lightweight and targets documentation tools, live editors (react-live), markdown tooling, and template-driven workflows.","status":"active","version":"0.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/react18-tools/esbuild-raw-plugin","tags":["javascript","esbuild","esbuild-plugin","tsup-plugin","raw-text-import","import-as-text","file-loader","raw-file-loader","code-import","typescript"],"install":[{"cmd":"npm install esbuild-raw-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-raw-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-raw-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for using the plugin with ESBuild or TSUP (which depends on ESBuild internally).","package":"esbuild","optional":false}],"imports":[{"note":"The package is ESM-only. CommonJS require will fail. Named export 'raw' is the plugin factory.","wrong":"const raw = require('esbuild-raw-plugin')","symbol":"raw","correct":"import { raw } from 'esbuild-raw-plugin'"},{"note":"A default export exists but is deprecated; prefer named import 'raw' for clarity.","wrong":"import { default as rawDefault } from 'esbuild-raw-plugin'","symbol":"default","correct":"import rawDefault from 'esbuild-raw-plugin'"},{"note":"TypeScript type import is recommended; if imported as value, it will be 'undefined' at runtime.","wrong":"import { RawPluginOptions } from 'esbuild-raw-plugin' (when used as a type only, TypeScript may warn)","symbol":"RawPluginOptions","correct":"import type { RawPluginOptions } from 'esbuild-raw-plugin'"}],"quickstart":{"code":"import { 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}).catch(() => process.exit(1));\n\n// Then in your source:\nimport code from './example.js?raw';\nconsole.log(code);\n","lang":"typescript","description":"Shows how to add the raw plugin to ESBuild and import a file as raw text string."},"warnings":[{"fix":"Upgrade to >=0.3.0 for proper binary loader support.","message":"Binary loaders fixed in v0.3.0: earlier versions may not correctly resolve binary file imports.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Replace `import raw from 'esbuild-raw-plugin'` with `import { raw } from 'esbuild-raw-plugin'`.","message":"Default export 'rawDefault' is deprecated since v0.2.0: use named export 'raw' instead.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Ensure that the 'ext' option includes required extensions, e.g., raw({ ext: ['.ts', '.tsx'] })","message":"Auto-import feature may fail if the resolved file does not exist; smart fallback requires proper extension configuration.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use `defineConfig({ esbuildPlugins: [raw()] })` instead of `plugins: [raw()]` in tsup config.","message":"When using the plugin with TSUP, ensure it is placed in the 'esbuildPlugins' array, not in 'plugins' which is for tsup plugins.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add `declare module '*?raw' { const content: string; export default content; }` to a .d.ts file.","message":"TypeScript declarations for raw imports (e.g., '*?raw') are required to avoid type errors; the plugin does not automatically generate them.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install the package: `npm install esbuild-raw-plugin --save-dev` and use ES module imports (e.g., `import { raw } from 'esbuild-raw-plugin'`).","cause":"Missing install or using CommonJS require with an ESM-only package.","error":"Cannot find module 'esbuild-raw-plugin'"},{"fix":"Add declare module '*?raw' { const content: string; export default content; }' to your global .d.ts file.","cause":"TypeScript cannot find type declarations for raw imports.","error":"Module '\"*.ts?raw\"' has no exported member 'default'."},{"fix":"Call the function: `plugins: [raw()]` instead of `plugins: [raw]`.","cause":"Incorrect usage of the plugin (e.g., passing raw directly without calling raw()).","error":"Error: The plugin 'raw' must be an object with a 'name' property, or a function returning one."},{"fix":"Use named import: `import { raw } from 'esbuild-raw-plugin'`.","cause":"Using default import but the package no longer exports a default export in newer versions.","error":"The requested module 'esbuild-raw-plugin' does not provide an export named 'default'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}