CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-rollup--plugin-url

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@rollup/plugin-url

@rollup/plugin-url is a Rollup plugin that imports files as data-URIs or ES Modules. It automatically processes static assets like images, fonts, and other binary files by either inlining small files as data-URIs for performance optimization or copying larger files to the output directory with hashed filenames to prevent caching issues.

Package Information

  • Package Name: @rollup/plugin-url
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @rollup/plugin-url --save-dev

Core Imports

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

For CommonJS:

const url = require('@rollup/plugin-url');

Basic Usage

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

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

Import assets in your source code:

// Import an image - returns either a data-URI or file path
import imageUrl from './assets/logo.png';
import iconSvg from './icons/home.svg';

console.log(`Image URL: ${imageUrl}`);

Capabilities

Plugin Factory Function

Creates a Rollup plugin instance for processing file imports as data-URIs or ES modules.

/**
 * Creates a Rollup plugin for importing files as data-URIs or ES Modules
 * @param options - Configuration options for the plugin
 * @returns Rollup plugin object
 */
function url(options?: RollupUrlOptions): Plugin;

interface RollupUrlOptions {
  /** 
   * File patterns to include in processing
   * @default ['**/*.svg', '**/*.png', '**/*.jp(e)?g', '**/*.gif', '**/*.webp']
   */
  include?: FilterPattern;
  /** 
   * File patterns to exclude from processing
   * @default undefined
   */
  exclude?: FilterPattern;
  /** 
   * File size limit in bytes for inlining
   * Files larger than this will be copied instead of inlined
   * Set to 0 to copy all files
   * @default 14336 (14kb)
   */
  limit?: number;
  /** 
   * String prefix for non-inlined file paths
   * @default ''
   */
  publicPath?: string;
  /** 
   * Whether to emit files to output directory
   * Set to false for server-side builds
   * @default true
   */
  emitFiles?: boolean;
  /** 
   * Template for output filenames
   * Supports [hash], [name], [extname], [dirname] placeholders
   * @default '[hash][extname]'
   */
  fileName?: string;
  /** 
   * Source directory for [dirname] replacement
   * @default ''
   */
  sourceDir?: string;
  /** 
   * Destination directory for copied assets
   * @default ''
   */
  destDir?: string;
}

type FilterPattern = string | RegExp | Array<string | RegExp>;

interface Plugin {
  name: string;
  load(id: string): Promise<string | null>;
  generateBundle(outputOptions: any): Promise<void>;
}

Basic Configuration:

export default {
  plugins: [
    url({
      limit: 8192, // 8kb limit
      include: ['**/*.png', '**/*.jpg', '**/*.svg'],
      publicPath: '/assets/'
    })
  ]
};

Advanced Configuration:

import path from 'path';

export default {
  plugins: [
    url({
      limit: 0, // Copy all files (no inlining)
      fileName: '[dirname][name].[hash][extname]',
      sourceDir: path.join(__dirname, 'src'),
      destDir: 'dist/assets',
      publicPath: 'https://cdn.example.com/assets/'
    })
  ]
};

Server-side Rendering:

export default {
  plugins: [
    url({
      emitFiles: false, // Prevent file emission for SSR builds
      publicPath: '/static/'
    })
  ]
};

File Processing Logic

The plugin processes files based on size and configuration:

  1. File Filtering: Uses include/exclude patterns to determine which files to process
  2. Size Check: Compares file size against the limit option
  3. Small Files (≤ limit): Converted to data-URIs
    • Images: Base64-encoded data-URIs (data:image/png;base64,iVBOR...)
    • SVG: URI-encoded data-URIs (data:image/svg+xml,<encoded-svg>)
      • SVG files undergo special processing: newlines/tabs removed, comments stripped, single quotes escaped
      • Brackets and parentheses are percent-encoded for URL safety
  4. Large Files (> limit): Copied to output directory
    • Filename generated using template with hash for cache-busting
    • Returns file path prefixed with publicPath

Filename Template Placeholders

When emitFiles is true and files exceed the size limit, the fileName template supports these placeholders:

  • [hash]: SHA-1 hash of file contents (first 16 characters)
  • [name]: Original filename without extension
  • [extname]: File extension including the leading dot
  • [dirname]: Parent directory name or relative path from sourceDir

Template Examples:

// Default: '[hash][extname]'
// logo.png → 'a1b2c3d4e5f6g7h8.png'

// '[name].[hash][extname]'
// logo.png → 'logo.a1b2c3d4e5f6g7h8.png'

// '[dirname][hash][extname]'
// assets/logo.png → 'assets/a1b2c3d4e5f6g7h8.png'

Supported File Types

By default, these file types are processed:

  • SVG: Vector graphics (**/*.svg)
  • PNG: Raster images (**/*.png)
  • JPEG: Raster images (**/*.jp(e)?g)
  • GIF: Animated images (**/*.gif)
  • WebP: Modern image format (**/*.webp)

Custom File Types:

export default {
  plugins: [
    url({
      include: [
        '**/*.svg', '**/*.png', '**/*.jpg', '**/*.gif', '**/*.webp',
        '**/*.woff', '**/*.woff2', '**/*.eot', '**/*.ttf' // Add fonts
      ]
    })
  ]
};

Error Handling

The plugin handles common error scenarios:

  • File not found: Returns null from the load hook, letting Rollup handle the error
  • File system errors: Read/stat failures from fs.readFile and fs.stat are propagated as build errors
  • Directory creation failures: Errors from makeDir during file emission are propagated
  • Copy operation failures: Stream errors during file copying (from fs.createReadStream/fs.createWriteStream) are propagated
  • Invalid options: Plugin uses default values for undefined options, applies filtering via @rollup/pluginutils

Integration Examples

With TypeScript:

// rollup.config.ts
import url from '@rollup/plugin-url';
import type { RollupOptions } from 'rollup';

const config: RollupOptions = {
  plugins: [
    url({
      limit: 10240,
      include: ['**/*.png', '**/*.svg'],
      publicPath: '/static/'
    })
  ]
};

export default config;

With Vite (Rollup-based):

// vite.config.js
import { defineConfig } from 'vite';
import url from '@rollup/plugin-url';

export default defineConfig({
  build: {
    rollupOptions: {
      plugins: [
        url({
          limit: 8192,
          publicPath: '/assets/'
        })
      ]
    }
  }
});

Multiple Build Targets:

// rollup.config.js
export default [
  // Client build
  {
    input: 'src/client.js',
    plugins: [url({ emitFiles: true, publicPath: '/assets/' })]
  },
  // Server build
  {
    input: 'src/server.js',
    plugins: [url({ emitFiles: false, publicPath: '/assets/' })]
  }
];

docs

index.md

tile.json