A plugin to transform image/video file imports into JS objects / properties with meta information
note: If you are reading this on npm, please note that this README is only updated per release. Sometimes deficiencies in the README are fixed in master but not yet published so make sure to check the github (and open an issue :D) page if something here is incorrect!
When building an application using server-side rendering, the need to calculate aspect ratios from image or video files in order to prevent layout jank often arises. While looking for alternatives — as to not have to write this myself — I stumbled upon some other packages:
These seem to primarily concern themselves with outputting a prefixed
path based off of the import statement, however. This does not include getting
the width
, height
, or aspectRatio
of a given image / video.
This plugin attempts to solve these issues by providing a simple way to
get what you need without having to jump through many hoops / module bundlers.
Transforms the following:
import avatar from 'avatar.jpg';
Into:
var avatar = {
pathname: '/avatar.jpg',
src: '/avatar.jpg',
width: 280,
height: 280,
aspectRatio: 1,
heightToWidthRatio: 1,
type: 'jpg'
};
dates are listed in dd-mm-yyyy format
image-size
with leather
, removing the need for ffprobe
🎉mkdirp
dependency, back to 2 deps :/md5-file
dependency, it's only 1 dep now 💥..svg
file content available through a content
property.md5
option to hash
, md5
now gets aliassed to hash
for backwards compat.
algo
option to specify a valid node crypto hash algorithm.This plugin is tested in the following NodeJS versions:
The plugin itself may work in older versions such as node 9 or maybe even 8 but mocha requires at least node version 10.13 for running tests.
Add this plugin to your package / application with:
npm:
npm install -S babel-plugin-transform-media-imports
yarn:
yarn add babel-plugin-transform-media-imports
Afterwards, add the plugin to your .babelrc
plugins:
{
"plugins": ["transform-media-imports"]
}
After following the installation steps above, you can now directly import
images and videos into your JS files. This will result in an object with some useful properties:
pathname
the path of the file with baseDir removed and pathnamePrefix prepended.src
the same as pathname
unless base64 was specified and the file size was less than base64.maxSize
.hash
when hash is enabled, this property contains the generated hash, undefined
otherwise.type
type of the media file, e.g. 'jpg'
, 'svg'
, 'mp4'
width
width in pixels of the media fileheight
height in pixels of the media filecontent
if the file is an svg
, the content
property will contain the raw svg file contents.aspectRatio
calculated aspect ratio using width / height
rounded to 3 decimal places.heightToWidthRatio
calculated ratio using height / width
rounded to 3 decimal places.To import
an image including all its properties:
import image from 'path/to/image.jpg';
Which will be transformed into:
var image = {
pathname: 'path/to/image.jpg',
src: 'path/to/image.jpg',
width: 1234,
height: 1234,
aspectRatio: 1,
heightToWidthRatio: 1,
type: 'jpg'
};
To export
an image including all its properties:
export {default as image} from 'path/to/image.jpg';
When using @babel/plugin-proposal-export-default-from, a default export can be used instead:
export image from 'path/to/image.jpg';
Either will be transformed into:
const _image = {
pathname: 'path/to/image.jpg',
src: 'path/to/image.jpg',
width: 1234,
height: 1234,
aspectRatio: 1,
heightToWidthRatio: 1,
type: 'jpg'
};
export { _image as image };
If you only need to import
a specific property, members may be imported using named imports:
import {width, height, heightToWidthRatio} from 'path/to/image.jpg';
Which will be transformed into:
const width = 1234;
const height = 1234;
const heightToWidthRatio = 1;
If you only need to export
a specific property, members may be exported using named exports:
export {width, height, heightToWidthRatio} from 'path/to/image.jpg';
Which will be transformed into:
export const width = 1234;
export const height = 1234;
export const heightToWidthRatio = 1;
This is the default configuration of the plugin, each option is detailed below:
[
'transform-media-imports',
{
baseDir: process.cwd(),
pathnamePrefix: '',
outputRoot: null,
imageExtensions: ['jpeg', 'apng', 'jpg', 'png', 'gif', 'svg', 'bmp', 'cur', 'ico', 'psd', 'dds'],
videoExtensions: ['mp4', 'webm', 'ogv'],
hash: false,
base64: false
}
]
default: process.cwd()
Everything before this path gets removed from the src
and pathname
attributes.
default: ''
After removing the baseDir
, the pathnamePrefix
gets prepended to
the src
and pathname
attributes.
default: null
When specified, writes output file(s) to outputRoot/{pathname}
where pathname
is the specified media file's pathname
attribute.
default: ['jpeg', 'apng', 'jpg', 'png', 'gif', 'svg', 'bmp', 'cur', 'ico', 'psd', 'dds']
Specify supported image extensions that will be transformed.
By default, all extensions that leather
supports are added to the list in addition to prepending 'jpeg'
and 'apng'
to allow
for regex matching of files using that extension as well.
default: ['mp4', 'webm', 'ogv']
Specify supported video extensions that will be transformed.
formerly named md5
, the old name is still supported and will work the same way
default: null
When set to true
, adds a hash to the src
and pathname
attributes:
import {pathname} from 'avatar.jpg';
Transforms into:
const pathname = 'avatar-3h2jk5gjkh35guighjg3hj5ghdjkahd34kj.jpg'
When set to an object, adds an md5 hash configured by it. The following properties are configurable:
{
length: 10, // trims md5 length to first <N> characters
delimiter: '.', // delimiter to join filename and md5: [filename][delimiter][md5].[ext]
algo: 'md5' // a valid node 'crypto' createHash algorithm such as md5 or sha256, defaults to md5
}
After applying the above configuration the import looks like this:
const pathname = 'avatar.3h2jk5gjkh.jpg'
default: null
When set to true
, sets the src
attribute to the base64 string including
web mime type when the file is <= 8192
bytes:
import {src} from 'avatar.jpg';
Transforms into:
var src = 'data:image/jpg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/4QCCRXhp...'
When set to an object, the maxSize
of 8192
may be overridden:
{
maxSize: 10000 // allow files up to 10kb to be transformed to base64
}