Installation

Installation

From GitHub

Not on npm yet. Install it straight from the repo:

npm i github:Abdulkader-Safi/s-img

npm clones the repo and builds it for you. dist/ is not committed, so a prepare script compiles it on install — which is why this works with no extra steps, and why the install takes a few seconds longer than a normal one.

Pin a branch, tag, or commit when you want to:

npm i github:Abdulkader-Safi/s-img#main
npm i github:Abdulkader-Safi/s-img#v0.1.0

Requirements

• Node 22.18+ or Bun. Both are tested on every PR.
• Nothing else. No compiler, no Python, no native toolchain, no platform-specific package.

That last point is most of the reason this library exists. There is no node-gyp step to fail on someone's laptop.

Check it works

import { supportedFormats, createImage, encode, decode, SImg } from 's-img';

console.log(supportedFormats().read); // ['png','jpeg','gif','bmp','tiff','webp']

const img = createImage(100, 60);
img.data.fill(200);
const png = await encode(img, 'png');
const out = await SImg.fromBuffer(png).maxLongEdge(20).toFormat('webp').toBuffer();
console.log((await decode(out)).width); // 20

If that prints 20, everything including the lazily-loaded WebP WASM is working.

TypeScript

Types ship with the package; there is no @types/s-img to install. It is ESM with bundled declarations, and it typechecks under strict with moduleResolution: nodenext.

import { SImg, type PipelineSpec, type Format } from 's-img';

Using it from a CommonJS project

The package is ESM only. A CJS consumer — an Obsidian plugin, say — gets there through its own bundler, which is what esbuild is for. Bundling is the normal path for a plugin anyway, because a plugin ships as a single main.js.

One thing to know if you bundle: the WebP WASM is reached through a dynamic import(), and that is deliberate. A bundler that can code-split leaves it as a separate chunk, and nobody who does not touch a WebP ever loads it. A bundler that cannot split (CJS output cannot) inlines it into your one file — you still pay nothing at runtime until a WebP is touched, because the module is not evaluated, but the bytes are in the file.

Working on both repos at once

npm link ../s-img

Skips the reinstall on every change. Remember that dist/ is what gets imported, so run npm run build in s-img after editing it — or npx tsc --watch.