{"id":19063,"library":"babel-plugin-file-loader","title":"babel-plugin-file-loader","description":"A Babel plugin that works like Webpack's file-loader for server-side rendering (SSR) apps. It processes import/require statements for image files, copies them to an output directory, and replaces the source with a public URL. The current stable version is 2.0.0, which upgrades to Babel 7. It supports configurable naming patterns with hashing, custom public paths, output paths, and extensions. This plugin is maintained by sheerun and has 95% test coverage. Key differentiators: it does not require Webpack, works with any Node.js build pipeline, and is specifically designed for isomorphic/SSR apps where Webpack's file-loader cannot run.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/sheerun/babel-plugin-file-loader","tags":["javascript","nextjs","babel","import","loader","static","images","cdn","sse"],"install":[{"cmd":"npm install babel-plugin-file-loader","lang":"bash","label":"npm"},{"cmd":"yarn add babel-plugin-file-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add babel-plugin-file-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Babel 7 plugin system","package":"@babel/core","optional":false}],"imports":[{"note":"Both import and require work; require is still supported but import is preferred for ES modules.","wrong":"const img = require('./file.png')","symbol":"default","correct":"import img from './file.png'"},{"note":"The plugin is named 'file-loader' in .babelrc, not the full package name. Version 2.x only works with Babel 7.","wrong":"\"plugins\": [[\"babel-plugin-file-loader\", {}]]","symbol":"babel-plugin-file-loader","correct":"\"plugins\": [\"file-loader\"]"},{"note":"Options must be in a nested array: [plugin, options]. A common mistake is to put options in the root plugins array.","wrong":"\"plugins\": [\"file-loader\", { \"publicPath\": \"/static\" }]","symbol":"with options","correct":"\"plugins\": [[\"file-loader\", { \"publicPath\": \"/static\", \"limit\": 10000 }]]"}],"quickstart":{"code":"// .babelrc\n{\n  \"plugins\": [\n    [\n      \"file-loader\",\n      {\n        \"name\": \"[hash].[ext]\",\n        \"extensions\": [\"png\", \"jpg\", \"jpeg\", \"gif\", \"svg\"],\n        \"publicPath\": \"/public\",\n        \"outputPath\": \"/public\",\n        \"context\": \"\",\n        \"limit\": 0\n      }\n    ]\n  ]\n}\n\n// app.js\nimport myImage from './image.png';\nconsole.log(myImage); // \"/public/0dcbbaa7013869e351f.png\"","lang":"javascript","description":"Configure babel-plugin-file-loader in .babelrc and use import to get a public URL for an image asset."},"warnings":[{"fix":"Upgrade to Babel 7 and ensure @babel/core is installed.","message":"Version 2.0.0 drops support for Babel 6; only Babel 7+ is supported.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use Webpack's file-loader or url-loader for client-side bundling; this plugin is for Node.js/SSR environments.","message":"The plugin does not work in browser builds; it only runs during Babel compilation (server-side/SSR).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you need the file to exist on disk, do not set outputPath to null.","message":"If outputPath is set to null, the file is not copied to disk; only the import is replaced with a public URL.","severity":"gotcha","affected_versions":">=1.1.0"},{"fix":"Use '[hash].[ext]' not '[hash].png'.","message":"The placeholder [ext] includes the dot (e.g., '.png'); the plugin adds a dot automatically, so do not include a dot in patterns.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Install the package: npm install babel-plugin-file-loader --save-dev. Ensure .babelrc uses \"file-loader\" (not \"babel-plugin-file-loader\") in the plugins array.","cause":"Missing babel-plugin-file-loader package or incorrect plugin name in .babelrc.","error":"Module not found: Can't resolve 'file-loader'"},{"fix":"Upgrade to Babel 7 and @babel/core, or downgrade the plugin to version 1.x.","cause":"Using Babel 6 with plugin version 2.x, which is incompatible.","error":"TypeError: (0 , _plugin.default) is not a function"},{"fix":"Add 'file-loader' to .babelrc plugins and ensure the extensions list includes the file type.","cause":"Babel is not configured to parse import statements for non-JS files (the plugin is missing).","error":"Unexpected token, expected \";\" when using import for image"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}