# webp-hero

> webp image format polyfill for browsers

Latest version **0.0.2** (published 2022-02-17) · ISC license · 0 weekly downloads

## Install

```sh
npm install webp-hero
pnpm add webp-hero
yarn add webp-hero
bun add webp-hero
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.2 |
| Published | 2022-02-17 |
| First published | 2017-12-16 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 4.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 254 |
| Author | Chase Moskal |
| Maintainers | chasemoskal |
| Keywords | webp, polyfill, webp-polyfill, image-conversion |

## Links

- npm: https://www.npmjs.com/package/webp-hero
- Repository: https://github.com/chase-moskal/webp-hero
- Homepage: https://github.com/chase-moskal/webp-hero#readme
- Issues: https://github.com/chase-moskal/webp-hero/issues
- npm.io page: https://npm.io/package/webp-hero

## 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

- 0.0.2 (latest) — 2022-02-17
- 0.0.1 — 2022-02-13
- 0.0.0 — 2022-02-13
- 0.0.0-dev.28 — 2022-02-12
- 0.0.0-dev.27 — 2020-10-21
- 0.0.0-dev.26 — 2020-08-27
- 0.0.0-dev.25 — 2020-08-27
- 0.0.0-dev.24 — 2019-09-03
- 0.0.0-dev.23 — 2019-05-31
- 0.0.0-dev.21 — 2019-04-29
- 0.0.0-dev.20 — 2019-04-23
- 0.0.0-dev.19 — 2019-03-19
- 0.0.0-dev.18 — 2019-02-27
- 0.0.0-dev.17 — 2019-02-25
- 0.0.0-dev.16 — 2019-02-24
- … 15 more at https://npm.io/package/webp-hero/versions

## README

🦸‍♂️ webp-hero
============

browser polyfill for the webp image format
------------------------------------------

- 📦 `npm install webp-hero`
- 🎉 webp images come alive, even in safari and ie11! _(firefox and edge now support webp)_
- ⚙️ webp-hero actually runs google's `libwebp` decoder in the browser _(converts webp images to png on-the-fly)_
- 🕹️ live demo
	- [webp-hero/](https://webp-hero.chasemoskal.com/) — webp-hero polyfill operating normally _(does nothing if your browser supports webp)_
	- [webp-hero/?force](https://webp-hero.chasemoskal.com/?force) — webp conversion to png is forced _(even if your browser supports webp)_
	- [webp-hero/?force&useCanvasElements](https://webp-hero.chasemoskal.com/?force&useCanvasElements) — wholly replace webp image elements with canvas elements _(added for icecat compatibility)_
- ♻️ freshness
	- [libwebp def64e9](https://github.com/webmproject/libwebp/tree/def64e920ff69e1d8270a2787d13df7c0d38d8ba) — 2020-08-17
	- [emscripten 2.0.1](https://github.com/emscripten-core/emscripten/releases/tag/2.0.1) — 2020-08-21
- 💯 browser support tested 2020-08-26
	- evergreen browsers (chrome, firefox, edge, desktop safari)
	- windows 7 ie11
	- iphone 7 mobile safari
	- galaxy s5 samsung internet
	- icecat 60.7 *(requires option `{useCanvasElements: true}`)*
- ⚖️ `98 KB`
- ⚠️ known issues and deficiencies
	- doesn't yet support css background images (pull requests welcome!)
	- doesn't yet support `<picture>` elements
	- doesn't yet support web workers (decodes images one-at-a-time, blocking, single-threaded)
	- currently only detects webp images with filename ending in `.webp` extension
	- no wasm (because older browsers)

webp-hero installation and usage
--------------------------------

- **option A — html install, use webp-hero's bundle with the polyfills**  
	you just inject the html onto your page. this technique works nicely for older browsers like ie11

	1. load generic polyfills and the webp-hero global bundle via script tags

		```html
		<script src="https://unpkg.com/webp-hero@0.0.1/dist-cjs/polyfills.js"></script>
		<script src="https://unpkg.com/webp-hero@0.0.1/dist-cjs/webp-hero.bundle.js"></script>
		```

	2. run the webp-hero polyfill function on the document

		```html
		<script>
			var webpMachine = new webpHero.WebpMachine()
			webpMachine.polyfillDocument()
		</script>
		```

- **option B — commonjs install, use webp-hero's cjs modules in your application**  
	you'll be familiar with this if you're bundling a commonjs with browserify or webpack  

	1. install the webp-hero npm package

		`npm install webp-hero`

	2. import and run the webp-hero polyfill function

		```js
		import {WebpMachine} from "webp-hero"
		const webpMachine = new WebpMachine()
		webpMachine.polyfillDocument()
		```

	3. *if* you want to support old browsers like ie11,  
		you might want to include your own polyfills or import `webp-hero/dist-cjs/polyfills.js`

- **option C — es-module install, like in the future**  
	es modules are available. but why would anybody use these for webp-hero? i guess it could be useful for.. mobile safari? anyways, this won't work in older browsers, which might defeat the purpose of using webp-hero in the first place? well.. it's here for you if you need it!

	1. use webp-hero on your page in one script tag

		```html
		<script type="module">
			import {WebpMachine} from "https://unpkg.com/webp-hero@0.0.1/dist/webp-machine.js"
			const webpMachine = new WebpMachine()
			webpMachine.polyfillDocument()
		</script>
		```

- **option D — angular users should look at [ngx-webp-polyfill](https://github.com/turnstileweb/ngx-webp-polyfill)**

webp-hero advanced usage
------------------------

### webp-machine

- [webp-machine.ts](./source/webp-machine.ts) has logic for polyfilling, caching, and enforcing sequential webp decoding
	- `new WebpMachine({...options})` — all options have defaults, but you can override them
		- `{webp}` google module which contains the actual decoder
		- `{webpSupport}` function which detects whether the browser supports webp
		- `{detectWebpImage}` detect whether or not the provided `<img>` element is in webp format
		- `{useCanvasElements: true}` boolean which when true causes webp-hero to polyfill webp images by wholly replacing them with canvas elements (instead of using png data urls). this helps compatibility with icecat (default: false)
	- the webpMachine you create has the following methods
		- `webpMachine.polyfillDocument()` — run over the entire html document, sniffing out webp `<img>` elements to convert (only if the browser doesn't support webp)
		- `webpMachine.polyfillImage(imageElement)` — converts the given webp image (only if the browser doesn't support webp)
		- `webpMachine.decode(webpData)` — decode webp `Uint8Array` data, return a png data-url
		- `webpMachine.clearCache()` — manually wipe the cache to save memory
- other modules like `convert-binary-data.ts` and etc may be unstable, you might not want to rely on those

### manual-style with the google libwebp decoder

- we compile from google's libwebp emscripten build in a docker container
- this build contains minimal functionality for rendering webp data to a canvas:
	- google's emscripten output: `webp-hero/libwebp/google/webp.js`
- we do little hacks to wrap this build into two modules:
	- common-js: `webp-hero/libwebp/webp.cjs.js`
	- es-module: `webp-hero/libwebp/webp.js`
- we have a typescript declaration for it too: [webp.d.ts](./libwebp/source/webp.d.ts)

webp-hero dev and contributing
------------------------------

- **prerequisites**
	- git and node
	- docker (only if you want to rebuild google's libwebp)

- **webp-hero development**
	- `npm install` — install dependencies and run build
		- runs a typescript build, uses browserify to make the bundle
		- generates `webp-hero/dist/` and `webp-hero/dist-cjs/`
		- generates the polyfills (cjs-only)
		- does *not* rebuild google's libwebp
	- `npm start` — start http server
		- visit http://localhost:5000/ to see the webp-hero demo
		- visit http://localhost:5000/libwebp/dist/google/ to see google's demo

- **rebuild google's libwebp**
	- libwebp build artifacts in `libwebp/dist` are checked into git, because it takes so damn long to build
	- `libwebp/build` — run dockerized libwebp build, regenerates `libwebp/dist`
	- `libwebp/debug` — handy for debugging the dockerized build

---
_Source: https://npm.io/package/webp-hero · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._