# bun-image-transform
> A bun plugin to import and transform image on the go
Latest version **1.1.3** (published 2024-05-22) · MIT license · 0 weekly downloads
## Install
```sh
npm install bun-image-transform
pnpm add bun-image-transform
yarn add bun-image-transform
bun add bun-image-transform
```
Provides the command `bun-image-transform`.
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; esm support; no vulnerabilities.
Warnings: low downloads.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.1.3 |
| Published | 2024-05-22 |
| First published | 2023-09-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 124.9 KB |
| Known vulnerabilities | 0 (+4 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 14 |
| Author | gungun974 |
| Maintainers | gungun974 |
| Keywords | bun, sharp, image |
## Links
- npm: https://www.npmjs.com/package/bun-image-transform
- Repository: https://github.com/gungun974/bun-image-transform
- Issues: https://github.com/gungun974/bun-image-transform/issues
- npm.io page: https://npm.io/package/bun-image-transform
## Dependencies (3)
- [sharp](https://npm.io/package/sharp.md) ^0.33.4
- [esbuild](https://npm.io/package/esbuild.md) ^0.21.3
- [commander](https://npm.io/package/commander.md) ^12.1.0
## Alternatives
- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads
## Recent versions
- 1.1.3 (latest) — 2024-05-22
- 1.1.2 — 2024-05-22
- 1.1.1 — 2023-10-26
- 1.1.0 — 2023-10-07
- 1.0.1 — 2023-09-18
## README
Bun Image Transform
Powered by [sharp](https://github.com/lovell/sharp) and [libvips](https://github.com/libvips/libvips).
## What is Bun Image Transform ?
Bun Image Transform is a plugin for the [Bun](https://github.com/oven-sh/bun) Bundler and Runtime capable of transforming an image upon import.
By default, Bun allows you to import and retrieve the file path, but sometimes you may want to import a high-resolution image directly from the source code, apply effects, and then compress it.
Bun Image Transform allows you to do exactly this.
## How to installed it
You will first need to install the package with Bun.
```bash
bun install bun-image-transform
```
Next, in your `tsconfig.json` file, you will need to add the library's typings to avoid "module not found" errors.
```json
{
"compilerOptions": {
"types": [
// other packages, e.g. "bun-types",
+ "bun-image-transform"
]
}
}
```
## ESBuild
Since version v1.1.0.
This Plugin has compatibility with ESBuild if you prefer ESBuild.
If you used the default import you would automatically use the correct Plugin however you can use `ESBuildImageTransformPlugin` if you prefer named import.
## Usages
### Runtime usage
To use as a runtime plugin, create a file that registers the plugin:
```ts
// preload.ts
import BunImageTransformPlugin from "bun-image-transform";
Bun.plugin(BunImageTransformPlugin());
```
Then preload it in your `bunfig.toml`:
```toml
preload = ["./preload.ts"]
```
### Bundler usage
To use this plugin, you will need to add it to your Bun build step.
```ts
import BunImageTransformPlugin from "bun-image-transform";
Bun.build({
entrypoints: ["./index.ts"],
// other config
plugins: [BunImageTransformPlugin()],
});
```
### Code usage
To use it in your code once the plugin is activated, you will simply need to load an image file as usual, with the exception that you will need to add modifiers like `?width=128&bunimg` after the file extension.
This syntax is similar to what one might find in the parameters of an HTTP GET method, but there is two **_major differences_**.
1. **The order matters**
2. **You can repeat the modifiers**
Also, some modifiers like `format` can receive information from special modifiers called **_"flags"_** that are placed **only behind them**.
```ts
import bunLogo from "./bun-logo.png?format=jpeg&bunimg";
console.log(bunLogo);
```
You can also use if you want `require` and `await import()`
```ts
require("./bun-logo.png?format=webp&bunimg");
await import("./bun-logo.png?quality=75&format=jpg&bunimg");
```
**Important** : You can't use dot to write number like `0.5` **you must use commas** like `0,5` or the file will not be resolve correctly
Note : Even though it's possible to transform an image with an `await import`, don't forget that the API remains limited in complex modifications, and you can simply perform the dynamic image transformations yourself using `sharp` directly.
### Modifiers
Bun Image Transform works by using the Node image processing library, sharp. Therefore, the available modifiers are directly taken from the sharp documentation.
| Property | Docs | Example | Comments |
| --------- | :-------------------------------------------------------------- | :------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| width | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `./bun-logo.png?width=128&bunimg` | See `enlarge` modifier. |
| height | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `./bun-logo.png?height=128&bunimg` | See `enlarge` modifier. |
| resize | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `./bun-logo.png?resize=128x128_#ffffff&bunimg` | The background color of the resize is optional. See `enlarge`, `kernel`, `fit` and `position` modifiers. |
| trim | [Docs](https://sharp.pixelplumbing.com/api-resize#trim) | `./bun-logo.png?trim&bunimg` |
| extend | [Docs](https://sharp.pixelplumbing.com/api-resize#extend) | `./bun-logo.png?extend={top}_{right}_{bottom}_{left}_[color]&bunimg` | Extend / pad / extrude one or more edges of the image with either the provided background color or pixels derived from the image. The background color is optional |
| extract | [Docs](https://sharp.pixelplumbing.com/api-resize#extract) | `./bun-logo.png?extract={left}_{top}_{width}_{height}&bunimg` | Extract/crop a region of the image. |
| format | [Docs](https://sharp.pixelplumbing.com/api-output#toformat) | `./bun-logo.png?format=png&bunimg` | Supported format: `png`, `jpg`, `jpeg`, `webp`, `avif`, `gif`, `heif` and `tiff` |
| rotate | [Docs](https://sharp.pixelplumbing.com/api-operation#rotate) | `./bun-logo.png?rotate=45&bunimg` |
| flip | [Docs](https://sharp.pixelplumbing.com/api-operation#flip) | `./bun-logo.png?flip&bunimg` |
| flop | [Docs](https://sharp.pixelplumbing.com/api-operation#flop) | `./bun-logo.png?flop&bunimg` |
| sharpen | [Docs](https://sharp.pixelplumbing.com/api-operation#sharpen) | `./bun-logo.png?sharpen=30&bunimg` |
| median | [Docs](https://sharp.pixelplumbing.com/api-operation#median) | `./bun-logo.png?median=10&bunimg` |
| blur | [Docs](https://sharp.pixelplumbing.com/api-operation#blur) | `./bun-logo.png?blur=5&bunimg` |
| gamma | [Docs](https://sharp.pixelplumbing.com/api-operation#gamma) | `./bun-logo.png?gamma=3&bunimg` |
| negate | [Docs](https://sharp.pixelplumbing.com/api-operation#negate) | `./bun-logo.png?negate&bunimg` |
| normalize | [Docs](https://sharp.pixelplumbing.com/api-operation#normalize) | `./bun-logo.png?normalize&bunimg` |
| threshold | [Docs](https://sharp.pixelplumbing.com/api-operation#threshold) | `./bun-logo.png?threshold=10&bunimg` |
| tint | [Docs](https://sharp.pixelplumbing.com/api-colour#tint) | `./bun-logo.png?tint=#00ff00&bunimg` |
| grayscale | [Docs](https://sharp.pixelplumbing.com/api-colour#grayscale) | `./bun-logo.png?grayscale&bunimg` | You can also use "greyscale" as a word. |
| modulate | [Docs](https://sharp.pixelplumbing.com/api-operation#modulate) | `./bun-logo.png?brightness=2&modulate&bunimg` | See `brightness`, `hue`, `lightness` and `saturation` flags. |
| render | \_ | `./bun-logo.png?trim&render&rotate=90&bunimg` | Apply all the previous modifiers and flatten them in this way. **Use only when needed**, as the transformed image will be stored in memory in a Buffer. |
### Flags
| Property | Docs | Example | Comments |
| ---------- | :------------------------------------------------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| kernel | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `./bun-logo.png?kernel=nearest&resize=128x128_#ffffff&bunimg` | Supported kernel: `nearest`, `cubic`, `mitchell`, `lanczos2` and `lanczos3` (default), for `resize` modifier |
| fit | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `./bun-logo.png?fit=fit_outside&resize=128x128_#ffffff&bunimg` | Sets `fit` option for `resize` modifier. |
| position | [Docs](https://sharp.pixelplumbing.com/api-resize#resize) | `./bun-logo.png?position=top&resize=128x128_#ffffff&bunimg` | Sets `position` option for `resize` modifier. |
| enlarge | \_ | `./bun-logo.png?enlarge&resize=1024x1024&bunimg` | For `width`, `height` and `resize` modifier. Allow the image to be upscaled. By default the returned image will never be larger than the source in any dimension, while preserving the requested aspect ratio. |
| quality | \_ | `./bun-logo.png?quality=80&format=webp&bunimg` | For `format` modifier and accepted values: 0 to 100 and need the format property to be apply |
| brightness | [Docs](https://sharp.pixelplumbing.com/api-operation#modulate) | `./bun-logo.png?brightness=2&modulate&bunimg` |
| hue | [Docs](https://sharp.pixelplumbing.com/api-operation#modulate) | `./bun-logo.png?hue=180&modulate&bunimg` |
| lightness | [Docs](https://sharp.pixelplumbing.com/api-operation#modulate) | `./bun-logo.png?lightness=50&modulate&bunimg` |
| saturation | [Docs](https://sharp.pixelplumbing.com/api-operation#modulate) | `./bun-logo.png?saturation=0,5&modulate&bunimg` |
### Settings
By default, image files will be generated in the .cache folder.
You can modify this behavior with the parameter below.
```ts
BunImageTransformPlugin({
outputDirectory: "customOutputFolder",
});
```
There are two more advanced options that allow you to disable the default behavior of the file loader and return a relative path to the output folder.
This behavior is perfectly suitable if you have a public folder on a web server where you want to directly place the generated images and work with the relative paths of that public folder.
```ts
BunImageTransformPlugin({
outputDirectory: "./build/public/img/",
useRelativePath: true,
prefixRelativePath: "img/",
});
```
## Credits
This project would not be possible without [Bun](https://github.com/oven-sh/bun) inspiring me to create this plugin.
To the project also [Sharp](https://github.com/lovell/sharp) for making it easy to transform and convert images.
And to the high-performance, secure, and easy-to-use image optimizer server, [IPX](https://github.com/unjs/ipx), which greatly inspired the syntax of the modifiers and usage.
## Experimental
This project has a command line to transform `bunimg://` urls like the plugin does directly but in a file.
This Command Line is not yet documented because it remains experimental.
## License
[MIT](./LICENSE)
---
_Source: https://npm.io/package/bun-image-transform · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._