better-asset

Config-driven image asset generator. Resize, convert, and generate favicons from a single JSON config.

Zero config UI. Just a JSON file and one command.

Install

npm install -g better-asset

Or use without installing:

npx better-asset

Quick Start

# Create a starter config
asset init

# Edit assets.config.json, then generate
asset

CLI

asset                  Generate assets from config
asset init             Create a starter config file
asset --config <path>  Use a custom config file
asset --help           Show help
asset --version        Show version

Supported Formats

Input: svg, png, jpg/jpeg, webp, avif

Output: png (default), webp, jpeg, avif, ico

Config File

By default better-asset looks for assets.config.json in the current directory.

Add a $schema key for editor autocompletion:

{
	"$schema": "https://unpkg.com/better-asset/assets.config.schema.json"
}

Example

{
	"$schema": "https://unpkg.com/better-asset/assets.config.schema.json",
	"source_dir": "public/assets",

	"assets": [
		{
			"name": "icon",
			"source": "icon.svg",
			"sizes": [48, 96, 144, 512],
			"destination": "public/icons"
		},
		{
			"name": "favicon",
			"source": "favicon.svg",
			"sizes": [16, 32, 48],
			"destination": "public/icons",
			"ico": {
				"required": true,
				"size": 96
			}
		},
		{
			"name": "opengraph-image",
			"source": "icon.svg",
			"sizes": ["1200x630"],
			"destination": "public/icons",
			"format": "jpeg"
		}
	]
}

Asset Fields

| Field | Type | Required | Default | Description | | ------------- | ----------------- | -------- | ------- | -------------------------------------------- | | name | string | yes | — | Base name for generated files | | source | string | yes | — | Source filename (relative to source_dir) | | sizes | array | yes | — | Sizes to generate | | destination | string | yes | — | Output directory (relative to project root) | | format | string | no | "png" | Output format: png, webp, jpeg, avif | | sizeInName | boolean | no | auto | Force include/exclude size in filename | | ico | boolean | object | no | — | Generate a favicon.ico |

Size Rules

Square — use a number:

48  →  48×48

Rectangular — use a string:

"1200x630"  →  1200×630

sizeInName

By default:

• Multiple sizes → size is included (icon-48.png, icon-96.png)
• Single size → size is omitted (apple-touch-icon.png)

Override per asset:

{ "sizeInName": true }
{ "sizeInName": false }

ICO Generation

Use ico as either a boolean shortcut or an object:

{ "ico": true }
{ "ico": false }

Or use the object form for more control:

{
	"ico": {
		"required": true,
		"size": 96
	}
}

| Field | Type | Required | Default | Description | | ---------- | ------- | -------- | ------- | -------------------------------------- | | required | boolean | yes | — | Whether to generate the .ico file | | size | number | no | 64 | Size of the embedded PNG in the .ico |

License

MIT