{"id":15021400,"url":"https://github.com/sidofc/babel-plugin-transform-media-imports","last_synced_at":"2025-10-28T16:31:24.412Z","repository":{"id":35055185,"uuid":"200548049","full_name":"SidOfc/babel-plugin-transform-media-imports","owner":"SidOfc","description":"A plugin to transform image/video file imports into JS objects / properties with meta information","archived":false,"fork":false,"pushed_at":"2023-04-21T22:05:01.000Z","size":1069,"stargazers_count":7,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-08T17:36:24.783Z","etag":null,"topics":["babel","babel-plugin","babel-transform-imports","npm-package"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/babel-plugin-transform-media-imports","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SidOfc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-04T22:34:03.000Z","updated_at":"2023-12-07T06:16:38.000Z","dependencies_parsed_at":"2024-06-19T16:23:47.913Z","dependency_job_id":"c5c90a6b-a1b0-4ebe-99e6-2dd28d77516b","html_url":"https://github.com/SidOfc/babel-plugin-transform-media-imports","commit_stats":{"total_commits":69,"total_committers":2,"mean_commits":34.5,"dds":0.04347826086956519,"last_synced_commit":"8f7a6e16dccfa60d6ff1ec1be1277bfc755b3a38"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SidOfc%2Fbabel-plugin-transform-media-imports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SidOfc%2Fbabel-plugin-transform-media-imports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SidOfc%2Fbabel-plugin-transform-media-imports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SidOfc%2Fbabel-plugin-transform-media-imports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SidOfc","download_url":"https://codeload.github.com/SidOfc/babel-plugin-transform-media-imports/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238680776,"owners_count":19512636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","babel-plugin","babel-transform-imports","npm-package"],"created_at":"2024-09-24T19:56:32.171Z","updated_at":"2025-10-28T16:31:19.026Z","avatar_url":"https://github.com/SidOfc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# babel-plugin-transform-media-imports\n\n![Licence](https://img.shields.io/badge/license-MIT-E9573F.svg)\n[![npm](https://img.shields.io/npm/v/babel-plugin-transform-media-imports)](https://www.npmjs.com/package/babel-plugin-transform-media-imports)\n[![Issues](https://img.shields.io/github/issues/SidOfc/babel-plugin-transform-media-imports.svg)](https://github.com/SidOfc/babel-plugin-transform-media-imports/issues)\n[![Build Status](https://circleci.com/gh/SidOfc/babel-plugin-transform-media-imports.svg?style=shield)](https://app.circleci.com/pipelines/github/SidOfc/babel-plugin-transform-media-imports)\n\n_note:_ If you are reading this on npm, please note that this README is only updated\n_per release_. Sometimes deficiencies in the README are fixed in master but not yet\npublished so make sure to check the github (and open an issue :D) page if something here is incorrect!\n\nWhen building an application using server-side rendering, the need to\ncalculate aspect ratios from image or video files in order to prevent\nlayout jank often arises.\nWhile looking for alternatives \u0026mdash; as to not have to write this\nmyself \u0026mdash; I stumbled upon some other packages:\n\n- [babel-plugin-transform-assets-import-to-string](https://github.com/yeojz/babel-plugin-transform-assets-import-to-string)\n- [babel-plugin-file-loader](https://github.com/sheerun/babel-plugin-file-loader)\n\nThese seem to primarily concern themselves with outputting a prefixed\npath based off of the import statement, however. This does not include getting\nthe `width`, `height`, or `aspectRatio` of a given image / video.\nThis plugin attempts to solve these issues by providing a simple way to\nget what you need without having to jump through many hoops / module bundlers.\n\nTransforms the following:\n\n```js\nimport avatar from 'avatar.jpg';\n```\n\nInto:\n\n```js\nvar avatar = {\n    pathname: '/avatar.jpg',\n    src: '/avatar.jpg',\n    width: 280,\n    height: 280,\n    aspectRatio: 1,\n    heightToWidthRatio: 1,\n    type: 'jpg'\n};\n```\n\n# Table of Contents\n\n- [babel-plugin-transform-media-imports](#babel-plugin-transform-media-imports)\n- [Table of Contents](#table-of-contents)\n- [Changelog](#changelog)\n    - [22-04-2023 v1.4.8](#22-04-2023-v148)\n    - [05-09-2022 v1.4.7](#05-09-2022-v147)\n    - [22-03-2022 v1.4.6](#22-03-2022-v146)\n    - [20-03-2022 v1.4.5](#20-03-2022-v145)\n    - [12-11-2021 v1.4.4](#12-11-2021-v144)\n    - [31-10-2021 v1.4.3](#31-10-2021-v143)\n    - [21-10-2021 v1.4.2](#21-10-2021-v142)\n    - [17-07-2021 v1.4.1](#17-07-2021-v141)\n    - [28-01-2021 v1.4.0](#28-01-2021-v140)\n    - [09-08-2019 v1.3.0](#09-08-2019-v130)\n    - [08-08-2019 v1.2.0](#08-08-2019-v120)\n    - [05-08-2019 v1.1.1](#05-08-2019-v111)\n- [Node support](#node-support)\n- [Installation](#installation)\n- [Usage](#usage)\n    - [Importing an image](#importing-an-image)\n    - [Exporting an image](#exporting-an-image)\n    - [Importing specific properties](#importing-specific-properties)\n    - [Exporting specific properties](#exporting-specific-properties)\n- [Configuration](#configuration)\n    - [baseDir](#basedir)\n    - [pathnamePrefix](#pathnameprefix)\n    - [outputRoot](#outputroot)\n    - [imageExtensions](#imageextensions)\n    - [videoExtensions](#videoextensions)\n    - [hash](#hash)\n    - [base64](#base64)\n\n# Changelog\n\n_dates are listed in dd-mm-yyyy format_\n\n### 22-04-2023 v1.4.8\n\n- Update dependencies\n\n### 05-09-2022 v1.4.7\n\n- Update dependencies\n- Test node 18\n\n### 22-03-2022 v1.4.6\n\n- Add package description\n\n### 20-03-2022 v1.4.5\n\n- Update dependencies\n\n### 12-11-2021 v1.4.4\n\n- Update dependencies\n\n### 31-10-2021 v1.4.3\n\n- Update dependencies\n\n### 21-10-2021 v1.4.2\n\n- Replace [`image-size`](https://github.com/image-size/image-size) with [`leather`](https://github.com/SidOfc/leather), removing the need for `ffprobe` :tada:\n\n### 17-07-2021 v1.4.1\n\n- Update dependencies, add node 16.5 to travis.yml\n\n### 28-01-2021 v1.4.0\n\n- Update dependencies (should have been a patch update, woops!)\n\n### 09-08-2019 v1.3.0\n\n- Add `mkdirp` dependency, back to 2 deps :/\n- Fix issues with creating directories recursively in older (\u003c 10.0.0) node versions\n\n### 08-08-2019 v1.2.0\n\n- Add ability to output files with [outputRoot](#outputroot).\n- Remove `md5-file` dependency, it's only 1 dep now :boom:.\n- Make `.svg` file content available through a `content` property.\n- Rename `md5` option to `hash`, `md5` now gets aliassed to `hash` for backwards compat.\n    - Add `algo` option to specify a valid node crypto hash algorithm.\n\n### 05-08-2019 v1.1.1\n\n- Added meta information\n\n# Node support\n\nThis plugin is tested in the following NodeJS versions:\n\n- Node.js 16.5.0\n- Node.js 15.0.0\n- Node.js 14.0.0\n- Node.js 13.0.0\n- Node.js 12.0.0\n\nThe plugin itself may work in older versions such as node 9 or maybe even 8\nbut mocha requires at least node version 10.13 for running tests.\n\n# Installation\n\nAdd this plugin to your package / application with:\n\n_npm_:\n\n```bash\nnpm install -S babel-plugin-transform-media-imports\n```\n\n_yarn_:\n\n```bash\nyarn add babel-plugin-transform-media-imports\n```\n\nAfterwards, add the plugin to your `.babelrc` plugins:\n\n```js\n{\n    \"plugins\": [\"transform-media-imports\"]\n}\n```\n\n# Usage\n\nAfter following the [installation](#installation) steps above, you can now directly `import`\nimages and videos into your JS files. This will result in an object with some useful properties:\n\n- `pathname` the path of the file with [baseDir](#basedir) removed and [pathnamePrefix](#pathnameprefix) prepended.\n- `src` the same as `pathname` unless [base64](#base64) was specified and the file size was less than `base64.maxSize`.\n- `hash` when [hash](#hash) is enabled, this property contains the generated hash, `undefined` otherwise.\n- `type` type of the media file, e.g. `'jpg'`, `'svg'`, `'mp4'`\n- `width` width in pixels of the media file\n- `height` height in pixels of the media file\n- `content` if the file is an `svg`, the `content` property will contain the raw svg file contents.\n- `aspectRatio` calculated aspect ratio using `width / height` rounded to 3 decimal places.\n- `heightToWidthRatio` calculated ratio using `height / width` rounded to 3 decimal places.\u003cbr\u003e\n  (useful for ::after padding aspect ratio hack)\n\n## Importing an image\n\nTo `import` an image including all its properties:\n\n```js\nimport image from 'path/to/image.jpg';\n```\n\nWhich will be transformed into:\n\n```js\nvar image = {\n    pathname: 'path/to/image.jpg',\n    src: 'path/to/image.jpg',\n    width: 1234,\n    height: 1234,\n    aspectRatio: 1,\n    heightToWidthRatio: 1,\n    type: 'jpg'\n};\n```\n\n## Exporting an image\n\nTo `export` an image including all its properties:\n\n```js\nexport {default as image} from 'path/to/image.jpg';\n```\n\nWhen using [\\@babel/plugin-proposal-export-default-from](https://babeljs.io/docs/en/next/babel-plugin-proposal-export-default-from.html),\na default export can be used instead:\n\n```js\nexport image from 'path/to/image.jpg';\n```\n\nEither will be transformed into:\n\n```js\nconst _image = {\n    pathname: 'path/to/image.jpg',\n    src: 'path/to/image.jpg',\n    width: 1234,\n    height: 1234,\n    aspectRatio: 1,\n    heightToWidthRatio: 1,\n    type: 'jpg'\n};\nexport { _image as image };\n```\n\n## Importing specific properties\n\nIf you only need to `import` a specific property, members may be imported using named imports:\n\n```js\nimport {width, height, heightToWidthRatio} from 'path/to/image.jpg';\n```\n\nWhich will be transformed into:\n\n```js\nconst width = 1234;\nconst height = 1234;\nconst heightToWidthRatio = 1;\n```\n\n## Exporting specific properties\n\nIf you only need to `export` a specific property, members may be exported using named exports:\n\n```js\nexport {width, height, heightToWidthRatio} from 'path/to/image.jpg';\n```\n\nWhich will be transformed into:\n\n```js\nexport const width = 1234;\nexport const height = 1234;\nexport const heightToWidthRatio = 1;\n```\n\n# Configuration\n\nThis is the default configuration of the plugin, each option is detailed below:\n\n```js\n[\n    'transform-media-imports',\n    {\n        baseDir: process.cwd(),\n        pathnamePrefix: '',\n        outputRoot: null,\n        imageExtensions: ['jpeg', 'apng', 'jpg', 'png', 'gif', 'svg', 'bmp', 'cur', 'ico', 'psd', 'dds'],\n        videoExtensions: ['mp4', 'webm', 'ogv'],\n        hash: false,\n        base64: false\n    }\n]\n```\n\n## baseDir\n\n**default**: `process.cwd()`\n\nEverything before this path gets removed from the `src` and `pathname` attributes.\n\n## pathnamePrefix\n\n**default**: `''`\n\nAfter removing the [`baseDir`](#basedir), the `pathnamePrefix` gets _prepended_ to\nthe `src` and `pathname` attributes.\n\n## outputRoot\n\n**default**: `null`\n\nWhen specified, writes output file(s) to `outputRoot/{pathname}` where `pathname`\nis the specified media file's `pathname` attribute.\n\n## imageExtensions\n\n**default**: `['jpeg', 'apng', 'jpg', 'png', 'gif', 'svg', 'bmp', 'cur', 'ico', 'psd', 'dds']`\n\nSpecify supported image extensions that will be transformed.\nBy default, all extensions that [`leather`](https://github.com/SidOfc/leather)\nsupports are added to the list in addition to prepending `'jpeg'` and `'apng'` to allow\nfor regex matching of files using that extension as well.\n\n## videoExtensions\n\n**default**: `['mp4', 'webm', 'ogv']`\n\nSpecify supported video extensions that will be transformed.\n\n## hash\n\n_formerly named `md5`, the old name is still supported and will work the same way_\n\n**default**: `null`\n\nWhen set to `true`, adds a hash to the `src` and `pathname` attributes:\n\n```js\nimport {pathname} from 'avatar.jpg';\n```\n\nTransforms into:\n\n```js\nconst pathname = 'avatar-3h2jk5gjkh35guighjg3hj5ghdjkahd34kj.jpg'\n```\n\nWhen set to an object, adds an md5 hash configured by it. The following properties\nare configurable:\n\n```js\n{\n    length: 10, // trims md5 length to first \u003cN\u003e characters\n    delimiter: '.', // delimiter to join filename and md5: [filename][delimiter][md5].[ext]\n    algo: 'md5' // a valid node 'crypto' createHash algorithm such as md5 or sha256, defaults to md5\n}\n```\n\nAfter applying the above configuration the import looks like this:\n\n```js\nconst pathname = 'avatar.3h2jk5gjkh.jpg'\n```\n\n## base64\n\n**default**: `null`\n\nWhen set to `true`, sets the `src` attribute to the base64 string including\nweb mime type when the file is `\u003c= 8192` bytes:\n\n```js\nimport {src} from 'avatar.jpg';\n```\n\nTransforms into:\n\n```js\nvar src = 'data:image/jpg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/4QCCRXhp...'\n```\n\nWhen set to an object, the `maxSize` of `8192` may be overridden:\n\n```js\n{\n    maxSize: 10000 // allow files up to 10kb to be transformed to base64\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidofc%2Fbabel-plugin-transform-media-imports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsidofc%2Fbabel-plugin-transform-media-imports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsidofc%2Fbabel-plugin-transform-media-imports/lists"}