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