New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

vite-imagetools

Package Overview
Dependencies
Maintainers
1
Versions
109
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

vite-imagetools - npm Package Compare versions

Comparing version 2.3.3 to 2.4.0-next.1

dist/directives/background.d.ts
dist/directives/quality.d.ts
dist/directives/resize.d.ts
dist/directives/rotate.d.ts
dist/index.cjs
dist/index.cjs.map
dist/output.d.ts
dist/types.d.ts
dist/util.d.ts

5

dist/directives/fit.d.ts

@@ -1,2 +0,3 @@

import { Directive } from "./index";
export declare const fitDirective: Directive;
import { FitEnum } from "sharp";
import { DirectiveContext, DirectiveOptions } from "../types";
export declare const fit: ({ fit }: DirectiveOptions, ctx: DirectiveContext) => keyof FitEnum;

8

dist/directives/format.d.ts

@@ -1,2 +0,6 @@

import { Directive } from "./index";
export declare const formatDirective: Directive;
import { Directive, ImageFormat } from "../types";
interface FormatOptions {
format: ImageFormat;
}
export declare const format: Directive<FormatOptions>;
export {};

11

dist/directives/index.d.ts

@@ -1,8 +0,3 @@

export interface Directive {
name: string;
with?: string[];
without?: string[];
test: (key: string, value: string) => boolean;
transform?: (key: string, value: string) => Record<string, any>;
}
export declare function directives(): Directive[];
export * from './resize';
export * from './format';
export * from './rotate';

5

dist/directives/kernel.d.ts

@@ -1,2 +0,3 @@

import { Directive } from "./index";
export declare const kernelDirective: Directive;
import { KernelEnum } from "sharp";
import { DirectiveContext, DirectiveOptions } from "../types";
export declare const kernel: ({ kernel }: DirectiveOptions, ctx: DirectiveContext) => keyof KernelEnum;

4

dist/directives/position.d.ts

@@ -1,2 +0,2 @@

import { Directive } from "./index";
export declare const positionDirective: Directive;
import { DirectiveContext, DirectiveOptions } from "../types";
export declare const position: ({ position }: DirectiveOptions, ctx: DirectiveContext) => any;

17

dist/index.d.ts

@@ -1,12 +0,5 @@

interface pluginOptions {
include?: Array<string | RegExp> | string | RegExp;
exclude?: Array<string | RegExp> | string | RegExp;
}
export default function (userOptions?: pluginOptions): {
name: string;
enforce: "pre";
buildStart(): Promise<void>;
configResolved(config: any): void;
load(assetPath: string): Promise<string>;
};
export {};
import { Plugin } from 'vite';
import { PluginOptions } from './types';
export * from './directives';
export * from './output';
export declare function imagetools(userOptions?: Partial<PluginOptions>): Plugin;

13

package.json
{
"name": "vite-imagetools",
"version": "2.3.3",
"main": "dist/index.js",
"version": "2.4.0-next.1",
"main": "dist/index.cjs",
"module": "dist/index.mjs",

@@ -20,7 +20,11 @@ "license": "MIT",

"dependencies": {
"@rollup/pluginutils": "^4.1.0",
"cacache": "^15.0.5",
"find-cache-dir": "^3.3.1",
"picomatch": "^2.2.2",
"rollup-pluginutils": "^2.8.2",
"sharp": "^0.27.0"
},
"devDependencies": {
"@types/cacache": "^15.0.0",
"@types/find-cache-dir": "^3.2.0",
"@types/jest": "^26.0.20",

@@ -36,3 +40,4 @@ "@types/picomatch": "^2.2.1",

"typedoc-plugin-markdown": "^3.4.3",
"typescript": "^4.1.3"
"typescript": "^4.2.3",
"vite": "^2.0.5"
},

@@ -39,0 +44,0 @@ "repository": {

411

README.md
# vite-imagetools :toolbox:
<!-- Demo gif -->
<!-- badges -->
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
A toolbox of custom import directives that can transform your images at compile-time.
<!-- Introduction -->
A toolbox of custom import directives that can transform your image at compile-time.
All of the image transformations are powered by [sharp](https://sharp.pixelplumbing.com).
> :warning: This is the development branch of v3! <br>
> Try it out and leave feedback via the issues!<br>
## v3 Roadmap
- [ ] ~Worker support~
- [x] Custom directives
- [ ] Query parameter passthrough
- [ ] Srcset output
- [x] Metadata output
- [ ] Full test coverage
- [x] **Resize** (i.e. `width`,`w`,`height`,`h`,`resize`)
- [x] **Rotate**
- [x] **Format** (`format` and it's shorthands)
- [ ] **flip**
- [ ] **flop**
- [ ] **sharpen**
- [ ] **blur**
- [ ] **median**
- [ ] **flatten**
- [ ] **gamma**
- [ ] **invert**
- [ ] **normalize**
- [ ] **tint**
- [ ] **grayscale**
- [ ] **toColorspace**
- [ ] **pad**
- [ ] **crop**
- [ ] **trim**
- [ ] **hue**
- [ ] **saturation**
- [ ] **brightness**
<!--
## Features
- **Output modern formats like avif or webp**
- **Resizing**
- **Generate SrcSets**
- **Custom import directives & output formats**
- **Image filters**
- **Import image metadata**
-->
## Table of Contents
- [Usage](#usage)
- [Install](#install)
- [Usage](#usage)
- [Options](#options)
- [Directives](#directives)
- [Caching](#caching)
- [Import directives](#import-directives)
- [Output formats](#output-formats)
- [Contributing](#contributing)
- [License](#license)
## Install
With [npm](https://npmjs.com):
```console
$ npm install --dev vite-imagetools
```
Or with [yarn](https://yarnpkg.com):
```console
$ yarn add --dev vite-imagetools
```
## Usage
Add the plugin to your vite config:
```typescript
import imagetools from 'vite-imagetools'
```js
import { imagetools } from 'vite-imagetools@next'

@@ -42,234 +78,215 @@ export default defineConfig({

```
The you can use all the directives when importing image files:
```html
<!-- This will transcode the image into webp-->
<img src="../assets/example.jpg?webp">
<!-- This resizes the image to be width x height pixels -->
<img src="../assets/example.jpg?size=500x300">
You use the query parameters to specify which transformations to apply to your image.
Each query parameter basically corresponds to a _pure function_ under the hood.
We call these parameters **Import Directives** and you can do a lot of powerful stuff with them.
For example the following diretive will turn the _jpg_ image into a _webp_ one and resize it to be 400 pixels wide:
```
import Logo from 'example.jpg?format=webp&width=400'
```
You can specify any number of directives to customize almost any aspect of the image:
```html
<img src="../assets/example.jpg?size=1200x900&fit=cover&position=top?webp">
The most common directives also allow you to use **shorthands**.<br>
```js
// the following statement
import logo from 'example.jpg?format=webp'
// can be shortened to
import logo from 'example.jpg?webp'
```
This for example will resize the image to 1200x900 pixels, using the object-fit cover and keeping the top of the image in view. It will also produce a webp image from the jpeg source.
You can of course also import images from javascript like so:
```typescript
import Image from 'example.jpg?format=avif'
### Multiple values
Instead of providing a single value to each directive you can give it a comma-separated list of values:
```
example.jpg?format=avif,webp&width=100,200,300
```
This will generate one image for each combination, so the above import statement will result in the following images:
```
example.jpg?format=avif,webp&width=100,200,300
└-> example.avif width=100
└-> example.avif width=200
└-> example.avif width=300
└-> example.webp width=100
└-> example.webp width=200
└-> example.webp width=300
```
### Options
This functionality is especially useful when generating responsive images, as you can easily generate a list of different widths.
(You can even generate a correct srcset as output! See [output formats](#output-formats)) for details.)
All plugin options are optional.
## Install
#### `include`
**Type**: _string_ | _RegExp_ | Array<_string_ | _RegExp_><br/>
Default: `['**/*.jpg', '**/*.jpg', '**/*.png', '**/*.webp', '**/*.webp', '**/*.avif', '**/*.gif', '**/*.heif']`<br/>
With npm:
```
npm install --dev vite-imagetools
```
Or with yarn:
```
yarn add --dev vite-imagetools
```
Which files to include when processing.
## Options
#### `exclude`
**Type**: string | RegExp | Array<string | RegExp><br/>
**Default**: `['public/**/*']`<br/>
### include
Which files to exclude when processing. By default this excludes vites _public_ folder to match the default behavior.
• **include**: *string* \| *RegExp* \| (*string* \| *RegExp*)[]
## Directives
Which paths to include when processing images.
`vite-plugin-imagset` works on a directive based workflow where you specify what transformation to apply in the import statement.
A **Directive** is basically a querystring field followed by an optional argument like you have seen above.
```
example.jpg?directive=argument
```
**`default`** '**\/*.{heic,heif,avif,jpeg,jpg,png,tiff,webp,gif}?*'
Commonly used directives also expose **Shorthands**. Shorthands have no arguments.
```
example.jpg?shorthand
```
A good example for shorthands is the [`format` directive](#format)
___
Directives can depend on other directives and some my be incompatible with others.
Directives can also be composed into more complex directives. (The `size` directive is a good example, it is composed from the `width` and `height` directives). See [the contributing section](#contributing) for details.
### exclude
Below is the list of all directives shipped by default:
• **exclude**: *string* \| *RegExp* \| (*string* \| *RegExp*)[]
---
#### `width`
**Argument**: <_number_><br/>
Resizes the image to have a with of `width` pixels. If not set, the height will be scaled automatically to match the width.
What paths to exclude when processing images.
This defaults to the public dir to mirror vites behavior.
```typescript
import Image from "example.jpg?width=300"
```
**`default`** 'public\/**\/*'
> You cannot use `with` and `size` together.
___
---
#### `height`
**Argument**: <_number_><br/>
Resize the image to have a height of `height` pixels. If not set, the width will be scaled automatically to match the height.
### cache
```typescript
import Image from "example.jpg?height=300"
```
• **cache**: *string* \| *false*
> You cannot use `height` and `size` together.
The path to use as the cache for images, set this option to false to disable caching completely.
---
#### `size`
**Argument**: <_width_>x<_height_><br/>
Sets width and height of the image simultaneously.
**`default`** 'node_modules/.cache/vite-imagetools'
```typescript
import Image from "example.jpg?size=1920x1080"
```
___
> When using `size` you cannot set `width` or `height`on the same resource.
### customDirectives
---
#### `fit`
**Argument**: <_'cover'_ | _'contain'_ | _'fill'_ | _'inside'_ | _'outside'_><br/>
How the image should be resized when both `width` and `height` are given.
If only one is specified this has no effect since the missing side will be scaled to keep the aspect ratio.
The default behavior when resizing is `cover`.
• **customDirectives**: [*Directive*](docs/modules/types.md#directive)<{}\>[]
**Shorthands**
- `cover`
- `contain`
- `fill`
- `inside`
- `outside`
You can use this option to extend the builtin list of import directives.
This list will be merged with the builtin directives before applying them to the input image.
See the section [Custom import directives](#custom-import-directives) for details.
---
#### `position`
**Argument**: < _'top'_ |
_'right top'_ |
_'right'_ |
_'right bottom'_ |
_'bottom'_ |
_'left bottom'_ |
_'left'_ |
_'left top'_ |
_'north'_ |
_'northeast'_ |
_'east'_ |
_'southeast'_ |
_'south'_ |
_'southwest'_ |
_'west'_ |
_'northwest'_ |
_'center'_ |
_'entropy'_ |
_'attention'_><br/>
When fit is `cover` or `contain` you can specify where the image should be anchored.
The behavior is similar to the [css object-postion](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) property.
For further details on the two special values `entropy` & `attention` see the [sharp documentation](https://sharp.pixelplumbing.com/api-resize#resize)
**`default`** []
**Shorthands**
- `top`
- `right top`
- `right`
- `right bottom`
- `bottom`
- `left bottom`
- `left`
- `left top`
- `north`
- `northeast`
- `east`
- `southeast`
- `south`
- `southwest`
- `west`
- `northwest`
- `center`
- `entropy`
- `attention
___
---
#### `kernel`
**Argument**: <_'nearest'_ | _'cubic'_ | _'mitchell'_ | _'lanczos2'_ | _'lanczos3'_><br/>
The interpolation kernel to use when resizing the image, the default value is `lanczos3`.
### customOutputFormats
---
#### `format`
**Argument**: <_'jpeg'_ | _'jpg'_ | _'webp'_ | _'avif'_ | _'png'_ | _'gif'_ | _'tiff'_ | _'heif'_><br/>
Transcodes the image to the give format. This directive will always be applied last.
> Some of these formats my not be available on your platform/setup
• **customOutputFormats**: [*OutputFormat*](docs/modules/types.md#outputformat)[]
Optionally you can use one of the Shorthands below like so:
```typescript
// instead of
import Image from "example.jpg?format=webp"
// you can write
import Image from "example.jpg?webp"
You can use this option to extend the builtin list of output formats.
This list will be merged with the builtin output formats before determining the format to use.
See the section [Custom output formats](#custom-output-formats) for details.
**`default`** []
___
### force
• **force**: *boolean*
By default vite-imagetools only generates output metadata during development mode
and only generates the actual images in build mode.
You can set this option to `true` to override this behaviour.
**`default`** false
## Caching
Processing a lot of images is quite resource intensive, that's why vite-imagetools caches all generated images on disk.
To take full advantage of this you want to configure your CI provider to persist the cache folder (`node_modules/.cache/vite-imagetools`) between builds.
> While cache eviction is not completely finished, it's a good idea to regularly delete the cache folder<br>
> Otherwhise you end up with gigabytes of wasted disk space!
## Import directives
Vite-imagetools provides a lot lot of directives out of the box, see the [big list of directives](./docs/directives.md)
### Custom import directives
## Output formats
Depending on your use-case just importing the url of the image might not be enough, <br>
that's why vite-imagetools let's you customize the exported data with output formats.
All the builtin formats are listed below.
> You can extend the list with the `customOutputFormats` option. See [Custom output formats](#custom-output-formats)
### url
This is the default format, it returns the url of the generated image.
```js
import imageUrl from 'example.jpg?width=300'
```
**Shorthands**:
- `jpeg`
- `jpg`
- `webp`
- `avif`
- `png`
- `gif`
- `tiff`
- `heif`
---
### `favicon`
_TODO_
> NOTE: If the specified directive generates multiple images the output will be an array of strings!
>```js
> import imageUrls from 'example.jpg?width=300,400,500'
>
> // imageUrls will be an Array
> console.log(imageUrls)
>```
---
### `rotate`
_TODO_
### metadata
---
### `flip`
_TODO_
You can import the whole set of image metadata by adding the `metadata` directive:
---
### `flop`
_TODO_
```jsx
import { src, width, height, format, channels } from 'example.jpg?width=300&webp?metadata'
---
### `sharpen`
_TODO_
// the src attribute holds the url to the image
const image = <img src={src}>
```
---
### `blur`
_TODO_
> NOTE: If the specified directive generates multiple images the output will be an array!
> ```jsx
> import images from 'example.jpg?width=300,400,500?metadata'
>
> // images is an array now
> const component => images.map(({src}) => <img src={src}>)
> ```
---
### `median`
_TODO_
### srcset
---
### `flatten`
_TODO_
---
### `gamma`
_TODO_
### Custom output formats
---
### `invert`
_TODO_
If the builtin output formats do not satisfy your needs you can easily extend add a custom format.
An output format is basically a function gets the outputMetadata objects and returns some value.
---
### `normalize`
_TODO_
> NOTE: While you can return any value from your format, it has to be JSON serializeable if you have json.stringify truned on!
## Contributing
So a format that only exports the width and height for some reason would look like this:
```ts
export const myCustomFormat: OutputFormat = (src: URL, outputMetadatas: Record<string, any>[]) => {
// you always get an array of metdatas
const out: string[] = outputMetadatas.map(metadata => ({ width, metadata.width, height: metadata.height }))
Saw a _TODO_ somewhere above? Chances are these are features I didn't have time for yet, so if you want this feature to be implemented have a look at the [custom directive section](#custom%20directives) below.
PRs are very welcome!
// this mirrors the behaviour of the builtin formats
// by returning the first element if only one is present
return out.length == 1 ? out[0] : out
}
```
See [the contributing file](CONTRIBUTING.md)!
Finally you have to tell vite-imagetools to take your format into consideration:
```js
import { imagetools } from 'vite-imagetools@next'
### Custom Directives
export default defineConfig({
plugins: [
imagetools({
customOutputFormats: [myCustomFormat]
})
]
})
```
_TODO_
## Contributing
## License
[MIT © Jonas Kruckenberg.](./LICENSE)
[MIT © Jonas Kruckenberg.](./LICENSE)
dist/directives/height.d.ts
dist/directives/size.d.ts
dist/directives/width.d.ts
dist/index.js
dist/index.js.map
dist/options.d.ts
dist/index.mjs

Sorry, the diff of this file is not supported yet

dist/index.mjs.map

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc