@rollup/plugin-url

What is @rollup/plugin-url?

@rollup/plugin-url is a Rollup plugin that allows you to import files as data-URIs or ES modules. This is particularly useful for handling assets like images, fonts, and other media files in your JavaScript projects.

What are @rollup/plugin-url's main functionalities?

Importing files as data-URIs

This feature allows you to import files (e.g., images) as data-URIs, which can be embedded directly into your JavaScript code. This is useful for small files that you want to include directly in your bundle.

import imageUrl from './image.png';

Importing files as ES modules

This feature allows you to import files as ES modules, which can be useful for larger files that you want to keep separate from your main JavaScript bundle. The plugin can be configured to decide when to use data-URIs and when to use ES modules based on file size.

import imageUrl from './image.png';

Customizing file handling

This feature allows you to customize how files are handled by specifying options like file size limits, file types to include, and whether to emit files to the output directory. This gives you fine-grained control over how assets are managed in your project.

import url from '@rollup/plugin-url';

export default {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'es'
  },
  plugins: [
    url({
      limit: 10 * 1024, // 10 KB
      include: ['**/*.svg', '**/*.png', '**/*.jpg', '**/*.gif'],
      emitFiles: true // Emit files to output directory
    })
  ]
};

Other packages similar to @rollup/plugin-url

url-loader

url-loader is a webpack loader that works similarly to @rollup/plugin-url. It allows you to import files as data-URIs or emit them as separate files based on a size limit. It is specifically designed for use with webpack, whereas @rollup/plugin-url is designed for Rollup.

file-loader

file-loader is another webpack loader that handles importing files. Unlike url-loader, it always emits files to the output directory and returns the URL to the file. This can be useful for larger assets that you don't want to include directly in your JavaScript bundle.

rollup-plugin-image

rollup-plugin-image is a Rollup plugin that allows you to import image files as data-URIs. It is more specialized than @rollup/plugin-url, focusing specifically on image files, whereas @rollup/plugin-url can handle a wider range of file types.

README

@rollup/plugin-url

🍣 A Rollup plugin which imports files as data-URIs or ES Modules.

Requirements

This plugin requires an LTS Node version (v14.0.0+) and Rollup v1.20.0+.

Install

Using npm:

npm install @rollup/plugin-url --save-dev

Usage

Create a rollup.config.js configuration file and import the plugin:

import url from '@rollup/plugin-url';

export default {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [url()]
};

Then call rollup either via the CLI or the API.

With an accompanying file src/index.js, the local image.svg file would now be importable as seen below:

// src/index.js
import svg from './image.svg';
console.log(`svg contents: ${svg}`);

Options

exclude

Type: String | Array[...String]
Default: null

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should ignore. By default no files are ignored.

include

Type: String | Array[...String]
Default: ['**/*.svg', '**/*.png', '**/*.jp(e)?g', '**/*.gif', '**/*.webp']

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default .svg, .png, .jpg, .jpeg, .gif and .webp files are targeted.

limit

Type: Number
Default: 14336 (14kb)

The file size limit for inline files. If a file exceeds this limit, it will be copied to the destination folder and the hashed filename will be provided instead. If limit is set to 0 all files will be copied.

publicPath

Type: String
Default: (empty string)

A string which will be added in front of filenames when they are not inlined but are copied.

emitFiles

Type: Boolean
Default: true

If false, will prevent files being emitted by this plugin. This is useful for when you are using Rollup to emit both a client-side and server-side bundle.

fileName

Type: String
Default: '[hash][extname]'

If emitFiles is true, this option can be used to rename the emitted files. It accepts the following string replacements:

• [hash] - The hash value of the file's contents
• [name] - The name of the imported file (without its file extension)
• [extname] - The extension of the imported file (including the leading .)
• [dirname] - The parent directory name of the imported file (including trailing /)

sourceDir

Type: String
Default: (empty string)

When using the [dirname] replacement in fileName, use this directory as the source directory from which to create the file path rather than the parent directory of the imported file. For example:

src/path/to/file.js

import png from './image.png';

rollup.config.js

url({
  fileName: '[dirname][hash][extname]',
  sourceDir: path.join(__dirname, 'src')
});

Emitted File: path/to/image.png

destDir

Type: String
Default: (empty string)

The destination dir to copy assets, usually used to rebase the assets according to HTML files.

Meta

CONTRIBUTING

LICENSE (MIT)