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

2.0.0 verified Sat Apr 25 auth: no javascript

Babel plugin that transforms asset imports and requires (e.g., images, SVGs) into CDN URL strings with content-based hashing. Version 2.0.0 is the current stable release, requiring Node.js 20+ and @babel/core ^7.20.0. It supports both ESM import and CommonJS require, configurable file extensions, hash length, output directory for copying assets, and path preservation. Differentiators include isomorphic/SSR focus, TypeScript typings, and simple setup without a module bundler. Release cadence is low; the plugin has had only a few updates since its initial 1.0.0 release.

Common errors

error Cannot find module 'babel-plugin-transform-assets-import-to-string' ↓

cause Plugin not installed as devDependency.

fix

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

error Plugin/Preset files are not allowed to export objects, only functions. ↓

cause Using an outdated Babel version that doesn't support default exports from plugins? Or invalid plugin config.

fix

Ensure @babel/core is ^7.20.0 and plugin is imported correctly (as default).

error baseUri option is missing or empty; paths will not be prefixed ↓

cause Missing required option (though optional technically, likely a configuration oversight).

fix

Add "baseUri": "https://mycdn.com/assets" to plugin options.

error Error: ENOENT: no such file or directory, copyfile '...' -> '...' ↓

cause outputDir specified but directory does not exist or is not writable.

fix

Create the output directory or ensure write permissions. Use absolute paths or adjust relative path.

Warnings

breaking Node.js >=20 required since v2.0.0; older versions incompatible. ↓

fix Upgrade Node.js to 20 or later, or pin to v1.0.1 if Node <20 is needed.

breaking @babel/core peer dependency changed from ^7.0.0 to ^7.20.0 in v2.0.0. ↓

fix Update @babel/core to ^7.20.0 or later.

deprecated Default extensions list changed between v1 and v2? Unclear; check plugin documentation for current defaults. ↓

fix Explicitly specify `extensions` option if relying on defaults.

gotcha Missing `baseUri` option results in transformed paths without a prefix (just filenames with hashes). ↓

fix Always provide `baseUri` unless you intentionally want local relative paths.

gotcha File copying with `outputDir` only works during Babel transformation (e.g., build step), not at runtime. ↓

fix Ensure `outputDir` is set and Babel runs as part of build process if asset copying is needed.

Install

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

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

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

Imports

plugin

wrong

const plugin = require('babel-plugin-transform-assets-import-to-string')

correct

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

Package ships as default export; named imports not supported. CommonJS require works but ESM recommended.

BabelPluginOptions

wrong

import { BabelPluginOptions } from 'babel-plugin-transform-assets-import-to-string'

correct

import type { BabelPluginOptions } from 'babel-plugin-transform-assets-import-to-string'

For TypeScript type import; use `import type` syntax to avoid runtime inclusion.

plugin as assetsToCDN

wrong

const assetsToCDN = require('babel-plugin-transform-assets-import-to-string').default

correct

import assetsToCDN from 'babel-plugin-transform-assets-import-to-string'

When renaming the default import, simply assign a new name. Do not use `.default` with CommonJS.

Quickstart

Demonstrates basic usage with .babelrc configuration, transforming both ES import and CommonJS require to CDN URLs with content-hashed filenames.

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

// Input source file
import logo from './images/logo.svg';
import icon from './icons/icon.png';
const bg = require('./assets/bg.jpg');

// Transformed output:
// const logo = 'https://cdn.example.com/assets/logo.a1b2c3d4.svg';
// const icon = 'https://cdn.example.com/assets/icon.e5f6g7h8.png';
// const bg = 'https://cdn.example.com/assets/bg.jpg'; (no hash if hashLength=0)