{"id":25547,"library":"esraw","title":"esbuild-raw-plugin","description":"An ESBuild and TSUP plugin for importing files as raw text, base64, dataurl, binary, or file content. v0.3.1 is current, released in February 2025. The plugin supports query suffixes like ?raw, ?text, ?base64, ?binary, ?dataurl, ?file, and smart extension resolution. It uses a fast regex-based onLoad filter, requires no configuration for common cases, and works as both an ESBuild plugin and a TSUP esbuildPlugin. Differentiators include zero-config setup, TypeScript declarations, and fallback resolution for folders and missing extensions.","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 esraw","lang":"bash","label":"npm"},{"cmd":"yarn add esraw","lang":"bash","label":"yarn"},{"cmd":"pnpm add esraw","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only; CJS require will fail. Named export, not default.","wrong":"const raw = require('esbuild-raw-plugin');","symbol":"raw","correct":"import { raw } from 'esbuild-raw-plugin'"},{"note":"TypeScript users must use type import for the options interface.","symbol":"RawPluginOptions","correct":"import type { RawPluginOptions } from 'esbuild-raw-plugin'"},{"note":"Must append query suffix (?raw, ?text, etc.) to the import path. Default import, not named.","wrong":"import { content } from './example.js'","symbol":"*?raw","correct":"import content from './example.js?raw'"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { raw } from 'esbuild-raw-plugin';\n\nawait build({\n  entryPoints: ['src/index.ts'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [raw()],\n});\n\n// In your source file:\nimport code from './code?raw';\nconsole.log(code); // raw content as string","lang":"typescript","description":"Set up ESBuild with the raw plugin and import a file as raw text."},"warnings":[{"fix":"Upgrade to esbuild-raw-plugin@^0.3.0","message":"In v0.3.0, binary loaders were fixed. If you used v0.2.0 with binary imports, upgrade to v0.3.0+.","severity":"breaking","affected_versions":">=0.2.0 <0.3.0"},{"fix":"Use explicit extensions or upgrade to v0.1.0+ and rely on auto-resolution.","message":"In v0.1.0, automatic file extension resolution was introduced. Imports without extensions may resolve differently than in v0.0.0.","severity":"breaking","affected_versions":">=0.0.0 <0.1.0"},{"fix":"Use 'customLoaders' instead of 'ext'.","message":"The 'ext' option for custom extensions may be deprecated in future versions in favor of 'customLoaders'.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Add 'declare module \"*?raw\" { const content: string; export default content; }' to your declarations.d.ts","message":"When using TypeScript, you must add a module declaration for each query suffix (e.g., '*?raw') or type-checking will fail.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use 'customLoaders' to whitelist specific file types rather than relying on query suffixes.","message":"The plugin uses regex-based onLoad filters; very large numbers of imports may cause performance issues.","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":"Run 'npm install esbuild-raw-plugin --save-dev'","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'esbuild-raw-plugin'"},{"fix":"Use 'import { raw } from 'esbuild-raw-plugin''","cause":"Using default import instead of named import.","error":"TypeError: raw is not a function"},{"fix":"Add 'declare module \"*?raw\" { const content: string; export default content; }' to a .d.ts file","cause":"Missing TypeScript module declaration for '?raw' suffix.","error":"Module '\"./code?raw\"' has no default export"},{"fix":"Add 'customLoaders: { '.svg': 'text' }' to plugin options.","cause":"The plugin is not loaded or configured for that file type.","error":"Error: No loader is configured for \".svg\" files: file.svelte"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}