hub / github.com/ai/webp-in-css

github.com/ai/webp-in-css @0.9.0

Chat with this repo

repository ↗ · DeepWiki ↗ · release 0.9.0 ↗ · + Follow

15 symbols 22 edges 7 files 2 documented · 13%

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

WebP in CSS

PostCSS plugin and tiny JS script (175 bytes) to use WebP in CSS background.

This tool will make your images 25% smaller for Chrome, Firefox, and Edge. Safari will download the bigger JPEG/PNG image.

You add require('webp-in-css/polyfill') to your JS bundle and write CSS like:

.logo {
  width: 30px;
  height: 30px;
  background: url(/logo.png);
}

The script will set webp or no-webp class on <body> and PostCSS plugin will generate:

.logo {
  width: 30px;
  height: 30px;
  background: url(/logo.webp) no-repeat;
}
body.webp .logo {
  background-image: url(/logo.webp);
}
body.no-webp .logo, body.no-js .logo {
  background-image: url(/logo.png);
}

If you want to use addNoJs option, you need manually set no-js class on <body>. Polyfill will remove this class, if JS is enabled in the browser. Polyfill should be inserted in the <head>, without async or defer attributes, before css. addNoJs option is enabled by default.

Usage

Step 1: Install tool:

npm install --save-dev postcss webp-in-css

Step 2: convert all your JPEG/PNG images to WebP by [Squoosh]. Set checkbox on Lossless for PNG images and remove it for JPEG.

We recommend Reduce palette for most of the PNG images.

Save WebP images in the same places of JPEG/PNG images: img/bg.png → img/bg.webp.

Step 3: use `

` to insert WebP images in HTML:

```diff html - Screenshot +


**Step 4:** add JS script to your client-side JS bundle:

```diff js
+ import 'webp-in-css/polyfill'

Since JS script is very small (142 bytes), the best way for landings is to inline it to HTML:

```diff html
+


Note, that you need to put `<script>` inside `<body>`, not `<head>`.

**Step 5:** check do you use PostCSS already in your bundler.
You can check `postcss.config.js` in the project root,
`"postcss"` section in `package.json` or `postcss` in bundle config.

If you don’t have it already, add PostCSS to your bundle:

* For webpack see [postcss-loader] docs.
* For Parcel create `postcss.config.js` file.
  It already has PostCSS support.
* For Gulp check [gulp-postcss] docs.

**Step 6:** Add `webp-in-css/plugin` to PostCSS plugins:

```diff js
module.exports = {
  plugins: [
+   require('webp-in-css/plugin'),
    require('autoprefixer')
  ]
}

If you use CSS Modules in webpack add `modules: true` option: ```diff js module.exports = { plugins: [ - require('webp-in-css/plugin'), + require('webp-in-css/plugin')({ modules: true }), require('autoprefixer') ] }


We also recommend to put all images from CSS to preload content:

```diff html
+   <link rel="preload" as="image" type="image/webp" href="https://github.com/ai/webp-in-css/raw/0.9.0/logo.webp">
    <script><%= readFile('node_modules/webp-in-css/polyfill.js') %></script>
  </head>

[postcss-loader]: https://github.com/postcss/postcss-loader#usage [gulp-postcss]: https://github.com/postcss/gulp-postcss [Squoosh]: https://squoosh.app/ ## PostCSS Options

module.exports = {
  plugins: [
    require('webp-in-css/plugin')({ /* options */ }),
  ]
}

* `modules` boolean: wrap classes to `:global()` to support CSS Modules. `false` by default. * `webpClass` string: class name for browser with WebP support. * `noWebpClass` string: class name for browser without WebP support. * `addNoJs` boolean: add `no-js` class to selector. `true` by default. * `noJsClass` string: class name for browser without JS support. * `check` function: should return boolean if we need to change declaration, default: ```js decl => /\.(jpe?g|png)(?!(\.webp|.*[&?]format=webp))/i.test(decl.value) ``` * `rename` function: get a new file name from old name, like `(oldName: string) => string`, then `url(./image.png)` → `url(./image.png.webp)`. Often you will need to change `check` option too. ```js check: decl => /\.jpg/.test(decl.value) && !decl.value.includes("as=webp"), rename: url => url.replace(".jpg", ".jpg?as=webp") ```

Core symbols most depended-on inside this repo

removeHtmlPrefix

called by 3

plugin.js

processBackgroundValue

Shape

Function 9

Class 4

Method 2

Languages

TypeScript100%

Modules by API surface

plugin.js6 symbols

test/polyfill-webp.test.js3 symbols

test/polyfill-no-webp.test.js3 symbols

test/setup-body.js2 symbols

test/plugin.test.js1 symbols

For agents

$ claude mcp add webp-in-css \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact