https://github.com/magicdawn/handy-img
handy img tool and API
https://github.com/magicdawn/handy-img
compress handy-img img mozjpeg sharp squoosh
Last synced: 5 months ago
JSON representation
handy img tool and API
- Host: GitHub
- URL: https://github.com/magicdawn/handy-img
- Owner: magicdawn
- License: mit
- Created: 2020-05-17T08:12:24.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-11-08T17:39:02.000Z (11 months ago)
- Last Synced: 2025-05-07T21:45:30.484Z (5 months ago)
- Topics: compress, handy-img, img, mozjpeg, sharp, squoosh
- Language: TypeScript
- Homepage:
- Size: 1.82 MB
- Stars: 6
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# handy-img
> handy img tool and API
[](https://github.com/magicdawn/handy-img/actions/workflows/ci.yml)
[](https://codecov.io/gh/magicdawn/handy-img)
[](https://www.npmjs.com/package/handy-img)
[](https://www.npmjs.com/package/handy-img)
[](http://magicdawn.mit-license.org)
## compress Features
- [x] target mozjpeg / webp are supported. `@squoosh/cli` supports more format.
- [x] Node.js native addon, better performance than squoosh WASM version.
- [x] batch process, support `--files` glob or dir mode `--dir`
- [x] parallel compress. set your `UV_THREADPOOL_SIZE=64` (see [this](https://www.sebastienvercammen.be/your-libuv-thread-pool-size-is-too-small/)) and handy-img will use this as concurrency.
## Install
```sh
$ pnpm add -g handy-img
```
## or invoke without install
```sh
# pnpm, recommend
pnpm dlx handy-img
# or yarn 2
yarn dlx handy-img
# or npx/pnpx
npx handy-img
pnpx handy-img
```
## cli
just type `himg` or `handy-img`
```txt
$ himg
himg <命令>
命令：
himg compress compress file [aliases: c]
himg info show info for file [aliases: i]
选项：
--version 显示版本号 [布尔]
--help 显示帮助信息 [布尔]
缺少 non-option 参数：传入了 0 个, 至少需要 1 个
```
### `himg compress` or `himg c`
```
$ himg c -h
Compress img
$ handy-img compress
━━━ Options ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-f,--files #0 files as input
--ignore-case ignore case for -f,--files, default true
--glob-cwd #0 cwd used in glob
-t,--tokens,--show-tokens show available tokens
-o,--output #0 output patterns
--codec #0 Allowed codec: `mozjpeg` or `webp`
--metadata keep metadata(only available with --codec webp)
-q,--quality #0 quality
-d,--dir #0 compress whole dir, and output to dir_compressed
--dir-suffix #0 suffix to append to original dir name when using -d,--dir mode
-y,--yes exec commands, default false(only preview commands, aka dry run)
```
#### flags
| flag | desc | default | remark |
| --------------------------- | ---------------------------------------------------------------- | ------------- | ---------------------------------------------------- |
| `-f,--files` | specify input, | | glob supported, see globby & fast-glob |
| `--ignore-case` | ignore case when glob input | `true` | |
| `--glob-cwd` | cwd of `-f,--files` provided | `pwd` | |
| `-t,--tokens,--show-tokens` | show available tokens | | help you to decide the `-o,--output` flag, see below |
| `-o,--output` | output pattern | | |
| `--codec` | Allowed codec: `mozjpeg` or `webp` or `mozjpeg-raw` | `mozjpeg` | |
| `--metadata` | keep metadata(not available with `--codec mozjpeg-raw`) | `true` | keep exif data |
| `-q,--quality` | quality | `80` | encode quality, `0-100` |
| `-d,--dir` | compress whole dir, and output to dir_compressed | | |
| `--dir-suffix` | suffix to append to original dir name when using -d,--dir mode | `_compressed` | |
| `-O,--other,--other-files` | how to handle other files in dir mode | | `move` or `copy` none img files to newly created dir |
| `-y,--yes` | exec commands, default false(only preview commands, aka dry run) | `false` | |
## Usage
### `-d`, use dir mode
```sh
himg c -d ./your-dir-here -y
```
glob all imgs in the dir you provided, and output to a new directory, which name is original name + dir suffix
and img will keep same structure.
```sh
# example
himg c -d dir -q 85 -y
```
### about `-y,--yes`
without this option, you will see what input will be processed and what file will be generated.
but the compress action will not really execute. aka dry run.
```sh
--------------------------------------------------------------------------------
current previewing commands. After comfirmed, append -y or --yes flag to execute
--------------------------------------------------------------------------------
```
it's like a safety guard for a gun
### `-f,--files`, single or multiple files
use `-f,--files` if you have to
#### 1.decide input
#### 2.then use `-t,--tokens,--show-tokens` show available tokens
#### 3.write your output pattern & preview
example pattern `himg c -f './*.jpg' -t -o ':dir/:name_compressed.:ext'`
example pattern `himg c -f './*.jpg' -t -o ':dir/compressed/:name.:ext'`
#### 4.use `-y,--yes` to execute
## Which codec & quality should I choose ?
See
- https://tsev.dev/posts/2023-11-10-should-avif-be-the-dominant-image-format/
- AND https://github.com/magicdawn/magicdawn/issues/170#issuecomment-1858817900
## Changelog
[CHANGELOG.md](CHANGELOG.md)
## License
the MIT License http://magicdawn.mit-license.org