{"id":25436,"library":"esbuild-raw-loader","title":"esbuild-raw-plugin","description":"A lightweight ESBuild and TSUP plugin (v0.3.1) that allows importing any file as raw text, base64, data URL, binary, or file content with zero configuration. Supports query suffixes like `?raw`, `?text`, `?base64`, `?dataurl`, `?binary`, `?file`, and automatically resolves file extensions. Useful for loading code files in documentation, interactive demos with react-live, or template-driven workflows. Actively maintained with monthly releases on npm, ships TypeScript types, and integrates seamlessly with ESBuild and TSUP builds.","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-loader","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-raw-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-raw-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency — plugin hooks into esbuild's build process via onLoad callback.","package":"esbuild","optional":true},{"reason":"Optional peer dependency — plugin can be used via tsup's esbuildPlugins config.","package":"tsup","optional":true}],"imports":[{"note":"Named export; the plugin is ESM-only. CommonJS require('esbuild-raw-plugin').raw also works.","symbol":"raw","correct":"import { raw } from 'esbuild-raw-plugin'"},{"note":"Default import is supported as an alias to the named export.","symbol":"default","correct":"import raw from 'esbuild-raw-plugin'"},{"note":"TypeScript type export for configuring plugin options.","symbol":"RawPluginOptions","correct":"import { RawPluginOptions } from 'esbuild-raw-plugin'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { raw } from 'esbuild-raw-plugin';\n\nawait build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'out.js',\n  plugins: [raw({\n    loader: 'text',\n    ext: ['.ts', '.tsx', '.js', '.css', '.md'],\n    customLoaders: { '.scss': 'text', '.png': 'dataurl' }\n  })],\n});\n\n// In your source code:\nimport code from './example.ts?raw';\nconsole.log(code); // raw text of example.ts\nimport img from './image.png?base64';\nconsole.log(img); // base64-encoded image data URL","lang":"typescript","description":"Demonstrates how to use the plugin with ESBuild, import files with query suffixes, and configure custom loaders."},"warnings":[{"fix":"Update to >=0.3.0: npm install esbuild-raw-plugin@latest","message":"Binary loaders were fixed in v0.3.0 — upgrades from earlier versions may change behavior for base64/dataurl/binary imports.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Remove `ext` if you rely on default extension resolution, or keep for explicit control.","message":"The `ext` option (array of extensions) still works but the plugin no longer requires it; it now falls back to all known extensions. Old usage of `ext` may be redundant.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Place `raw()` before other esbuild plugins in the plugins array.","message":"The plugin uses a regex-based onLoad filter — it may not intercept imports that have already been handled by other plugins with higher priority. Ensure your plugin order in the array is correct.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add to declarations.d.ts: `declare module '*?raw' { const content: string; export default content; }`","message":"For TypeScript projects, you must add a module declaration for `*?raw` and other query suffixes to avoid type errors.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Specify full filename with extension to avoid ambiguity: import code from './file.ts?raw' instead of './file?raw'.","message":"The plugin resolves filenames without extensions by trying multiple extensions — this can cause unexpected file resolution if multiple files with same name but different extensions exist in the same directory.","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":"Ensure the plugin is correctly listed in `plugins` array and that you've imported `raw` properly.","cause":"esbuild does not natively handle `.raw` extensions; the query suffix `?raw` may not be stripped before looking up a loader.","error":"Error: No loader is configured for \".raw\" files"},{"fix":"Add `declare module '*?raw' { const content: string; export default content; }` to a .d.ts file.","cause":"TypeScript cannot resolve the query-suffixed import without a module declaration.","error":"Cannot find module './example.ts?raw' or its corresponding type declarations."},{"fix":"Use `const { raw } = require('esbuild-raw-plugin');` or `import { raw } from 'esbuild-raw-plugin';`.","cause":"Importing the default export incorrectly when using CommonJS require.","error":"TypeError: raw is not a function"},{"fix":"Update esbuild to >=0.8.0 and ensure you're using a compatible version.","cause":"esbuild version < 0.8 does not support query strings in import paths.","error":"Error: Build failed with 1 error: error: Unexpected \"?\""}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}