https://github.com/chase-moskal/webp-hero

browser polyfill for the webp image format
https://github.com/chase-moskal/webp-hero

browser-polyfill decoder polyfill webp webp-images

Last synced: 2 months ago
JSON representation

browser polyfill for the webp image format

Host: GitHub
URL: https://github.com/chase-moskal/webp-hero
Owner: chase-moskal
License: mit
Created: 2017-12-14T07:32:54.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2022-06-06T01:39:26.000Z (almost 3 years ago)
Last Synced: 2025-02-12T01:02:04.686Z (2 months ago)
Topics: browser-polyfill, decoder, polyfill, webp, webp-images
Language: CMake
Homepage: https://chasemoskal.com/webp-hero/
Size: 3.37 MB
Stars: 253
Watchers: 6
Forks: 22
Open Issues: 10
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

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 `` elements

	- doesn't yet support web workers (decodes images one-at-a-time, blocking, single-threaded)

	- 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

		

		

		```

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

		```html

		

			var webpMachine = new webpHero.WebpMachine()

			webpMachine.polyfillDocument()

		

		```

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

		

			import {WebpMachine} from "https://unpkg.com/[email protected]/dist/webp-machine.js"

			const webpMachine = new WebpMachine()

			webpMachine.polyfillDocument()

		

		```

- **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 `` 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 `` 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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/chase-moskal/webp-hero

Awesome Lists containing this project

README