babel-plugin-transform-assets-import-to-string

Babel plugin that transforms image assets import and requires to urls / cdn

Table of Contents

• About
• Features
• Requirements
• Installation
• Usage
  • via babelrc
  • via Node API
• Options
• Examples
  • Basic URI Transformation
  • File Copying with outputDir
  • Path Preservation with preservePaths
  • Disabling Hash

About

This babel plugin allows you to transform asset files into a string uri, allowing you to point your assets to CDN or other hosts, without needing to run your code through module bundlers.

This helps when doing isomorphic / server-rendered applications.

import image from '../path/assets/icon.svg';
const image1 = require('../path/assets/icon1.svg');

// to

const image = 'https://cdn.example.com/assets/icon.a1b2c3d4.svg';
const image1 = 'https://cdn.example.com/assets/icon1.e5f6g7h8.svg';

// Somewhere further down in your code:
//
// eg: JSX
// <img src={image} alt='' />
//
// eg: Other cases
// ajaxAsyncRequest(image)

See the spec for more examples.

Features

• Transforms asset imports to CDN URLs with content hashing
• Supports both ES6 import and CommonJS require()
• Optional file copying to output directory during build
• Content-based hashing for cache busting (same content = same hash)
• Configurable file extensions and hash length
• Path structure preservation option
• TypeScript support

Requirements

• Node.js 20 or higher
• Babel 7.20 or higher

Installation

$> npm install babel-plugin-transform-assets-import-to-string --save-dev

This plugin requires @babel/core as a peer dependency. If you don't already have it installed:

$> npm install @babel/core --save-dev

Usage

via .babelrc

{
  "plugins": [
    [
      "transform-assets-import-to-string",
      {
        "baseUri": "https://cdn.example.com/assets"
      }
    ]
  ]
}

via Node API

require('@babel/core').transform('code', {
  plugins: [
    [
      'transform-assets-import-to-string',
      {
        baseUri: 'https://cdn.example.com/assets'
      }
    ]
  ]
});

Options

Option	Type	Default	Description
baseUri	string	""	URL prefix for transformed paths (e.g., "https://cdn.example.com/assets")
outputDir	string	undefined	Directory to copy assets to during build. If not set, no files are copied.
extensions	string[]	[".gif", ".jpeg", ".jpg", ".png", ".svg"]	File extensions to transform. Leading . (dot) is required.
hashLength	number	8	Length of content hash in filename. Set to 0 to disable hashing.
preservePaths	string	undefined	Base path to strip while preserving directory structure. If not set, filenames are flattened.

Examples

Basic URI Transformation

Transform imports to CDN URLs with content hashing:

{
  "plugins": [
    [
      "transform-assets-import-to-string",
      {
        "baseUri": "https://cdn.example.com/assets"
      }
    ]
  ]
}

// Input
import logo from './images/logo.svg';

// Output
const logo = 'https://cdn.example.com/assets/logo.a1b2c3d4.svg';

File Copying with outputDir

Copy assets to a build directory during transformation:

{
  "plugins": [
    [
      "transform-assets-import-to-string",
      {
        "baseUri": "https://cdn.example.com/assets",
        "outputDir": "./dist/assets"
      }
    ]
  ]
}

// Input
import logo from './images/logo.svg';

// Output
const logo = 'https://cdn.example.com/assets/logo.a1b2c3d4.svg';
// File copied to: ./dist/assets/logo.a1b2c3d4.svg

Path Preservation with preservePaths

Keep directory structure by specifying a base path to strip:

{
  "plugins": [
    [
      "transform-assets-import-to-string",
      {
        "baseUri": "https://cdn.example.com",
        "outputDir": "./dist/static",
        "preservePaths": "src"
      }
    ]
  ]
}

// Input (file at src/components/icons/logo.svg)
import logo from './icons/logo.svg';

// Output
const logo = 'https://cdn.example.com/components/icons/logo.a1b2c3d4.svg';
// File copied to: ./dist/static/components/icons/logo.a1b2c3d4.svg

Without preservePaths, all files are flattened to the root of outputDir.

Disabling Hash

Use hashLength: 0 to disable content hashing:

{
  "plugins": [
    [
      "transform-assets-import-to-string",
      {
        "baseUri": "https://cdn.example.com/assets",
        "hashLength": 0
      }
    ]
  ]
}

// Input
import logo from './images/logo.svg';

// Output
const logo = 'https://cdn.example.com/assets/logo.svg';

Custom Extensions

Transform only specific file types:

{
  "plugins": [
    [
      "transform-assets-import-to-string",
      {
        "baseUri": "https://cdn.example.com/assets",
        "extensions": [".svg", ".png"]
      }
    ]
  ]
}

License

babel-plugin-transform-assets-import-to-string is MIT licensed