babel-plugin-file-loader

2.0.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Module not found: Can't resolve 'file-loader' ↓

cause Missing babel-plugin-file-loader package or incorrect plugin name in .babelrc.

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.

error TypeError: (0 , _plugin.default) is not a function ↓

cause Using Babel 6 with plugin version 2.x, which is incompatible.

fix

Upgrade to Babel 7 and @babel/core, or downgrade the plugin to version 1.x.

error Unexpected token, expected ";" when using import for image ↓

cause Babel is not configured to parse import statements for non-JS files (the plugin is missing).

fix

Add 'file-loader' to .babelrc plugins and ensure the extensions list includes the file type.

Warnings

breaking Version 2.0.0 drops support for Babel 6; only Babel 7+ is supported. ↓

fix Upgrade to Babel 7 and ensure @babel/core is installed.

gotcha The plugin does not work in browser builds; it only runs during Babel compilation (server-side/SSR). ↓

fix Use Webpack's file-loader or url-loader for client-side bundling; this plugin is for Node.js/SSR environments.

gotcha If outputPath is set to null, the file is not copied to disk; only the import is replaced with a public URL. ↓

fix If you need the file to exist on disk, do not set outputPath to null.

gotcha The placeholder [ext] includes the dot (e.g., '.png'); the plugin adds a dot automatically, so do not include a dot in patterns. ↓

fix Use '[hash].[ext]' not '[hash].png'.

Install

npm install babel-plugin-file-loader

yarn add babel-plugin-file-loader

pnpm add babel-plugin-file-loader

Imports

default
wrong
```
const img = require('./file.png')
```
correct
```
import img from './file.png'
```
Both import and require work; require is still supported but import is preferred for ES modules.
babel-plugin-file-loader
wrong
```
"plugins": [["babel-plugin-file-loader", {}]]
```
correct
```
"plugins": ["file-loader"]
```
The plugin is named 'file-loader' in .babelrc, not the full package name. Version 2.x only works with Babel 7.
with options
wrong
```
"plugins": ["file-loader", { "publicPath": "/static" }]
```
correct
```
"plugins": [["file-loader", { "publicPath": "/static", "limit": 10000 }]]
```
Options must be in a nested array: [plugin, options]. A common mistake is to put options in the root plugins array.

Quickstart

Configure babel-plugin-file-loader in .babelrc and use import to get a public URL for an image asset.

// .babelrc
{
  "plugins": [
    [
      "file-loader",
      {
        "name": "[hash].[ext]",
        "extensions": ["png", "jpg", "jpeg", "gif", "svg"],
        "publicPath": "/public",
        "outputPath": "/public",
        "context": "",
        "limit": 0
      }
    ]
  ]
}

// app.js
import myImage from './image.png';
console.log(myImage); // "/public/0dcbbaa7013869e351f.png"