Library / SDK
CatsJuice/sticker-forge avatar
CatsJuice/sticker-forge

Sticker Forge: a WebGL sticker maker you embed as a Web Component

A tactile WebGL sticker maker with rich text, image uploads, and interactive peel physics.

763 stars66 forksJavaScriptMIT

At a glance

What is it?
Sticker Forge renders text or uploaded artwork as a die-cut sticker with interactive peel physics, shipped as an interactive builder plus a framework-independent Web Component and imperative API under the MIT licence.
Who is it for?
Adopt Sticker Forge if you need a self-contained sticker renderer with peel physics that can be dropped into an existing page as a Web Component or mounted imperatively, and if you accept that the reusable surface is version 0.1.0 with no release history beyond the repository itself. Skip it if you need server-side rendering, a stable versioned CDN artifact, or a documented rollback path: the README does not describe one.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 113 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • CatsJuice/sticker-forge763 ★ · +29
Star history
Repository2026-09-172026-11-22
CatsJuice/sticker-forge734763

29 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Sticker Forge actually renders

Most sticker tools on the web are flat image compositors: you pick a border, you export a PNG. Sticker Forge is aimed at the interaction instead. The README describes the core behaviour directly: you grab the die-cut edge, drag it inward, and the sticker curls to reveal a back surface with depth-aware shadowing. That is a 3D deformation driven by pointer input, not a CSS transform.

The audience is narrow and specific. It is for developers building a web page or app that wants a sticker as a live object: a product page where the sticker peels, a demo where the user drags the corner, a share card that responds. The repository ships two deliverables for two different users. The builder in app/ is for someone who wants to produce artwork in a browser. The Web Component and imperative API in lib/ are for someone who wants to mount that renderer inside their own page. If you only need a static PNG of a sticker, this is more machinery than the job requires.

How the peel, lighting and material pipeline fit together

Three.js is a direct dependency, and the option surface in the README maps onto a lighting and material model rather than a 2D canvas. lighting.direction is a normalized view-space vector pointing from the sticker toward the incoming light, and per the README it drives surface shading and projected-shadow direction together. That coupling matters: you cannot set a shadow angle independently of the light, because they are the same value. lighting.intensity accepts 0 to 1.5, while ambient and softness use 0 to 1.

The peel model has its own units, and they are not uniform. peel.radius is normalized to the sticker's short side, so 0.12 means 12 percent regardless of pixel size. peel.maxAngle is in radians. peel.grabWidth is in CSS pixels at 100 percent scale and scales with the sticker, while shadow blur and distance are plain CSS pixels. Mixing normalized and absolute units in one options object is a real source of confusion when you tune a layout, and the README documents the split but does not offer a single unit convention.

Input handling branches on what you feed it. Text sources take text, color, fontFamily and fontWeight, and the engine waits for the requested browser font before rebuilding the texture. Image sources accept any browser-decodable URL, and the engine inspects decoded pixel alpha: transparent images use their alpha silhouette for the die-cut outline, fully opaque images fall back to the rectangular image boundary. That fallback is the honest limit of the approach. A JPEG of a sticker shape with a white background will not get a die-cut edge, because there is no alpha to read.

Installing Sticker Forge and mounting a first sticker

The README states Node.js 22.13 or newer is required, and package.json enforces it with an engines field of >=22.13.0. Clone the repository and install:

bash
npm install
npm run dev

The dev script runs vinext dev bound to 0.0.0.0 with the Wrangler log written to .wrangler/wrangler.log. To produce the hosted app and both reusable library bundles:

bash
npm run build

According to the README, the reusable files are emitted to public/embed/: sticker-forge.es.js auto-registers the <sticker-forge> element, sticker-forge.iife.js exposes window.StickerForge, and sticker-forge.d.ts carries the public TypeScript declarations. Copy the ES bundle into your page and add the element:

html
<script type="module" src="/embed/sticker-forge.es.js"></script>

<sticker-forge
  id="sticker"
  style="display:block;width:640px;height:420px"
></sticker-forge>

Then wait for the element to be defined and set a source. setSource() is asynchronous, and the README says the promise settles after the texture is ready, so await it before reading state:

js
await customElements.whenDefined("sticker-forge");
const sticker = document.querySelector("#sticker");

await sticker.setSource({
  type: "text",
  text: "PEEL ME",
  color: "#19191d",
  fontFamily: "Arial Rounded MT Bold, Arial Black, sans-serif",
  fontWeight: 900,
});

sticker.addEventListener("peelchange", (event) => {
  console.log("peel", event.detail.progress);
});

What you should see is a sticker rendered in the 640 by 420 box, draggable from its die-cut edge, with peelchange firing as you drag. The README points to examples/embed.html for a complete standalone page. If a custom element does not fit your host framework, createSticker(target, options) is asynchronous and resolves to the control object, and renderer events are dispatched from the target element you passed in.

The SVG sanitizer is the security-relevant part

Sticker Forge accepts raw SVG markup through setSource({ type: "svg", svg: svgMarkup }) and explicitly does not require pre-sanitization. The README states the library always removes scripts, event attributes, foreignObject and external URL references before rasterization, and that sanitizeSvgMarkup(svgMarkup) is exported when you need the sanitized markup itself.

That is a deliberate design choice with a clear trade-off. Accepting unsanitized markup lowers the integration cost for anyone piping user-supplied SVG through, and it puts the sanitization burden on the library rather than on every caller getting it right. The cost is that you are trusting this implementation's removal list. The README names four categories it strips; it does not publish a formal threat model or claim conformance to a published sanitizer specification, and the repository has no release history beyond version 0.1.0. If your threat model requires an audited sanitizer, run sanitizeSvgMarkup() yourself and inspect the output before it reaches setSource(), or reject raw SVG entirely and only accept raster uploads.

Audio is an audio sprite, not a timeline

The README is unusually explicit here, and it is worth reading before you tune the sound. The bundled recording is treated as an audio sprite rather than a timeline. Sticker Forge separates its lift, light crackle, strong tear and release material, compensates for their different levels, and drives randomized grains from the drag velocity and acceleration. The result described is: a slow peel is sparse, a fast peel is denser and brighter, holding still is silent, and reattaching uses a quieter low-passed texture instead of reversed audio. The README also notes progress is used only for the initial lift, so you should not expect the sound to track the peel amount linearly.

The asset itself is inlined. The provided peel sound is trimmed, converted to mono, lightly high-passed and embedded into both JavaScript bundles, so there is nothing to copy or host separately. The untouched source recording stays in lib/assets/. That inlining is convenient and it is also weight you cannot opt out of: if you load sticker-forge.es.js, you load the audio with it. sound.enabled and sound.volume are the only documented controls over it.

Where Sticker Forge is the wrong tool

The build targets are the first constraint. build:pages runs next build --webpack with GITHUB_PAGES=true and NEXT_PUBLIC_SITE_URL set to https://sticker.oooo.so, and the Pages workflow at .github/workflows/deploy-pages.yml deploys a static export on pushes to main. The README notes the production site's DNS record is a CNAME for the sticker subdomain pointing to catsjuice.github.io. That is a static hosting setup. There is no documented server-side rendering path for the sticker itself, and the renderer is WebGL, so there is nothing to render on the server anyway.

There is also no versioned distribution channel described. package.json marks the package private and sets version 0.1.0, and the README's install instructions are npm install inside the repository, not a published package install. If you want to pull a pinned bundle from a CDN, the README does not describe one. You build it and you host it.

The lifecycle API is the third limitation. The README lists destroy() and comments that you should call it before permanently removing the target in an SPA, which tells you the renderer holds resources that a route change will not clean up on its own. resize() and reset() are also on the control surface, and the README does not describe what resize() does to an in-progress peel. If your layout reflows mid-drag, that is untested ground from the documentation's perspective.

Finally, the die-cut outline depends on alpha. Fully opaque images get the rectangular boundary. Anyone expecting automatic contour extraction from a flat JPEG will be disappointed.

Alternatives and the actual difference

The nearest comparison is a 2D canvas sticker editor, the kind that draws a border around a rasterized image and exports a PNG. The difference is structural rather than cosmetic. A canvas editor composites pixels; it can fake a shadow by drawing another shape. Sticker Forge deforms geometry in a Three.js scene, which is why it can expose peel.radius, peel.stiffness, peel.maxAngle and a separate back surface with its own color, gloss and roughness. The canvas approach cannot produce a curl that reveals a back face, because there is no back face to reveal. The cost is the opposite of the benefit: a canvas editor works without WebGL and can render in contexts where a GPU-backed scene cannot.

The second alternative is rolling the effect yourself on top of Three.js. The repository's own dependency list shows three at ^0.185.1, so the underlying library is the same one you would reach for. What Sticker Forge adds on top is the die-cut outline derivation from alpha, the peel input model with its normalized units, the lighting coupling between shading and projected shadow, and the audio sprite handling. If you only need one of those, building directly on Three.js is less surface area to maintain. If you need the combination, reimplementing it is the larger job.

A third option is not using a live renderer at all and exporting a static image. The dependency list includes modern-screenshot, gifenc and prores-wasm-encoder, which suggests the hosted app is built around exporting results. If your requirement is a downloadable sticker rather than an interactive one, the builder in app/ is the relevant deliverable and the embed library is beside the point.

Maintenance, licence and what to verify

The repository is not archived, and the last push was on 2026-08-01. That is recent enough that the code is not abandoned, but it is a single data point and there is no release history to read: the README's recent releases section is empty, and package.json still says 0.1.0. Treat the API as pre-1.0. The README documents the control surface and the event detail shapes, but it does not document a deprecation policy or a compatibility guarantee between versions.

Licensing is straightforward on the surface: the repository declares MIT, and there is a THIRD_PARTY_NOTICES.md at the top level. That second file is the one to read before shipping, because the dependency list is broad and includes @huggingface/transformers, heic-decode, prores-wasm-encoder and gifenc alongside Three.js and React. The MIT licence covers the project's own code; the third-party notices file is where the terms for everything bundled with it are recorded. This is not legal advice, and if you are shipping a commercial product you should have someone read both files rather than assuming the top-level licence settles it.

Upgrade cost is the practical question. The build runs npm run typecheck before both build:lib and the app build, so a type error stops the bundle rather than shipping. The test script is npm run build followed by node --test tests/*.test.mjs, which means the test suite only runs after a full build succeeds. That is a slow feedback loop for a change to a lighting constant, and it is worth knowing before you fork.

Editorial conclusion

Adopt Sticker Forge if you need a self-contained sticker renderer with peel physics that can be dropped into an existing page as a Web Component or mounted imperatively, and if you accept that the reusable surface is version 0.1.0 with no release history beyond the repository itself. Skip it if you need server-side rendering, a stable versioned CDN artifact, or a documented rollback path: the README does not describe one. Before you build on it, run npm run build and confirm that public/embed/sticker-forge.es.js, sticker-forge.iife.js and sticker-forge.d.ts are all emitted, then call getState() after setSource() resolves to see what the library reports back.

Frequently asked questions

How do I create my own sticker pack with Sticker Forge?

The README does not describe a pack format or a batch export. It documents a single sticker at a time: call setSource() with a text or image source, then setOptions() to change the outline, material and peel settings. Anything resembling a pack would have to be assembled outside the library.

What is the difference between a GIF and a sticker in Sticker Forge?

Sticker Forge does not treat stickers as animated image files. It renders a live WebGL object with peel physics, and gifenc appears in the dependency list, which points to GIF being an export format from the hosted app rather than the sticker's runtime form. The README does not document GIF input.

What are types of stickers Sticker Forge can make?

The README documents text sources, image sources from any browser-decodable URL (including PNG, WebP, JPEG, GIF, AVIF and SVG data URLs), and legacy raw SVG markup. Material types are configurable through the material option, and the README's example uses holographic.

How to use a sticker maker like Sticker Forge?

Either run the builder in app/ with npm run dev, or embed the library. The embed path is to load public/embed/sticker-forge.es.js, add a <sticker-forge> element, await customElements.whenDefined, then await setSource() before listening for peelchange.

Official sources

  1. CatsJuice/sticker-forge on GitHub
  2. Issues
  3. License: MIT
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/catsjuice-sticker-forge.svg)](https://hysenlabs.com/projects/catsjuice-sticker-forge)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/catsjuice-sticker-forge.svg)](https://hysenlabs.com/projects/catsjuice-sticker-forge)

Was this useful?