Tilted sphere with longitudinal stripes Modern Web Guides Docs Blog

Building Rollup Plugin Import Meta Assets

Rollup plugin that detects assets references relative to modules using patterns such as new URL('./assets/my-img.png', import.meta.url).

The referenced assets are added to the rollup pipeline, allowing them to be transformed and hash the filenames.

How it works

A common pattern is to import an asset to get the URL of it after bundling:

import myImg from './assets/my-img.png';

This doesn't work in the browser without transformation. This plugin makes it possible to use an identical pattern using import.meta.url which does work in the browser:

const myImg = new URL('./assets/my-img.png', import.meta.url);

Install

Using npm:

npm install @web/rollup-plugin-import-meta-assets --save-dev

Usage

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

import { importMetaAssets } from '@web/rollup-plugin-import-meta-assets';

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

Then call rollup either via the CLI or the API.

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: null

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.

warnOnError

Type: Boolean
Default: false

By default, the plugin quits the build process when it encounters an error. If you set this option to true, it will throw a warning instead and leave the code untouched.

transform

Type: Function
Default: null

By default, referenced assets detected by this plugin are just copied as is to the output directory, according to your configuration.

When transform is defined, this function will be called for each asset with two parameters, the content of the asset as a Buffer and the absolute path. This allows you to conditionnaly match on the absolute path and maybe transform the content.

In this example, we use it to optimize SVG images with svgo:

import { importMetaAssets } from '@web/rollup-plugin-import-meta-assets';
const svgo = new SVGO({
  // See https://github.com/svg/svgo#what-it-can-do
  plugins: [
    /* plugins here */
  ],
});

export default {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'es',
  },
  plugins: [
    importMetaAssets({
      transform: (assetBuffer, assetPath) => {
        return assetPath.endsWith('.svg')
          ? svgo.optimize(assetBuffer.toString()).then(({ data }) => data)
          : assetBuffer;
      },
    }),
  ],
};

Examples

Source directory:

.
├── one
│   └── two
│       └── the-image.svg
├──
└── entrypoint.js

With entrypoint.js containing this:

const imageUrl = new URL('./one/two/the-image.svg', import.meta.url).href;
console.log(imageUrl);

Output directory:

.
├── assets
│   └── the-image.svg
└── bundle.js

With bundle.js containing this:

const imageUrl = new URL(new URL('asset/the-image.svg', import.meta.url).href, import.meta.url)
  .href;
console.log(imageUrl);