Fájlok hostolása & CORS

Hol éljen a .riv fájl, a fallback kép, és a hivatkozott assetek (fontok, képek), és milyen HTTP-fejléceket állíts be (cache, CORS).

Akkor használd, ha

• Most döntöd el, hová tegyed a .riv fájlt, amit a Lupiantól kaptál.
• Az animáció lokálisan jól megy, de a stagingen / élesben elszáll.
• Új verziót akarsz éleszteni úgy, hogy a felhasználók ne lássák a régit.

Mire lesz szükséged

• Egy hely a statikus fájloknak: saját szerver, az app public/ mappája, CDN (Cloudflare, Vercel, Netlify, S3+CloudFront stb.).
• Jogosultság az ottani HTTP-fejlécek beállítására (CORS, cache).

Három hely, ahol a .riv élhet

1. Az app bundle-jében (public/)

new Rive({ src: "/animations/hero.riv", canvas, autoplay: true });

• Azonos origin → CORS nem gond.
• A legtöbb bundler automatikusan cache-buster nevet ad, vagy használhatsz ?v=2 query-t.
• Kisebb fájloknál (néhány száz KB-ig) ez a jó alapértelmezés.

2. CDN-en / statikus hoston

new Rive({ src: "https://cdn.your-site.com/rive/hero.riv", canvas, autoplay: true });

• Hosszú cache-eléshez ideális. Állítsd be a Cache-Control: public, max-age=31536000, immutable fejlécet, és új tartalomnál cseréld a fájlnevet (hero.v2.riv).
• CORS kell, ha másik originen él, mint az oldal. Lásd lejjebb.

3. Előre ArrayBufferként letöltve

const buf = await fetch("/animations/hero.riv").then(r => r.arrayBuffer());
new Rive({ buffer: buf, canvas, autoplay: true });

• Hasznos, amikor az időzítést te akarod kézben tartani (pl. egy szekció megjelenése előtt töltöd be).

CORS — a leggyakoribb éles-buktató

Ha a .riv más originen van, mint az oldal, ami betölti, a kiszolgálónak muszáj ezt visszaadnia:

Access-Control-Allow-Origin: https://your-site.com

(vagy * teljesen publikus eszközökhöz).

Hoston belüli gyors útmutató:

Host	Hol állítsd a CORS-t
Cloudflare R2	Bucket → Settings → CORS Policy
AWS S3	Bucket → Permissions → CORS configuration (JSON)
Cloudflare CDN	Transform Rule → Modify Response Headers
Vercel	vercel.json → headers blokk
Netlify	_headers fájl vagy netlify.toml
Nginx	add_header Access-Control-Allow-Origin ...;

Vercel példa (vercel.json):

{
  "headers": [{
    "source": "/(.*)\\.riv",
    "headers": [
      { "key": "Access-Control-Allow-Origin", "value": "*" },
      { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
    ]
  }]
}

Tünet, ha hiányzik a CORS fejléc: a .riv URL 200-at ad a DevTools Network fülén, de a Console-on „blocked by CORS policy” üzenet látszik, és az onLoadError elsül. Lásd: Nem töltődik be az animáció.

Cache-stratégia

A .riv fájlok adott verzión belül megváltoztathatatlanok. A legbiztosabb minta:

1. Cserélj fájlnevet, amikor a tartalom változik — hero.v2.riv, hero-2026-05-21.riv, vagy hero.<hash>.riv.
2. Állítsd be a Cache-Control: public, max-age=31536000, immutable fejlécet a fájlon.
3. A kódban írasd át a hivatkozást az új fájlnévre.

Így a felhasználók sosem látnak elavult .riv-et, és a böngésző sem tölti le újra a még érvényeset.

Ha nem tudsz nevet cserélni, query paramétert is használhatsz: hero.riv?v=2. A böngésző a query-t a cache-kulcs részeként kezeli.

Hivatkozott fontok / képek

Néhány .riv fájl referenced asset módot használ — a font vagy kép a .riv-en kívül él, és futásidőben tölti be. A handoff.md jelzi, ha ez vonatkozik rád.

new Rive({
  src: "/animations/hero.riv",
  canvas,
  autoplay: true,
  assetLoader: (asset, bytes) => {
    // bytes.length === 0 → "referenced", neked kell letölteni.
    if (asset.isFont && bytes.length === 0) {
      fetch(`/fonts/${asset.name}.woff2`)
        .then(r => r.arrayBuffer())
        .then(b => asset.decode(new Uint8Array(b)));
      return true;
    }
    return false; // a beágyazott / hosztolt assetekkel hagyd dolgozni a runtime-ot
  },
});

A Lupian-csomagok többsége embedded asseteket használ — erre csak akkor van szükség, ha a handoff.md referenced fontokat vagy képeket sorol fel. Teljes API: rive.app/docs.

CSP (Content Security Policy)

Ha az oldalad CSP fejlécet küld, engedélyezd a WASM-ot:

script-src 'self' 'wasm-unsafe-eval';

A wasm-unsafe-eval nélkül a runtime el sem indul. Lásd: Nem töltődik be az animáció.

A fallback kép

A fallback képet (PNG/SVG) ugyanúgy helyezd el, mint a .riv-et. Akkor mutasd:

• Amíg a .riv tölt.
• Ha az onLoadError elsül.
• Ha a böngészőben nincs WebGL.

<div class="rive-mount" style="position:relative;">
  <img src="/animations/hero.fallback.png" alt="" style="width:100%; height:100%;">
  <canvas id="rive-canvas" style="position:absolute; inset:0; opacity:0;"></canvas>
</div>
<script type="module">
  // betöltéskor fade-in a canvasra, hibánál marad a kép
</script>

Gyakori hibák

• A .riv másik originen, CORS nélkül — egyes böngészők némán buknak el, mások egyértelmű konzolhibát adnak.
• Nincs Cache-Control fejléc — minden látogatáskor friss letöltés, lassabb első festés.
• Ugyanaz a fájlnév több verzión át — a felhasználók addig látják a régit, amíg ki nem ürítik a cache-t.
• Hiányzik a wasm-unsafe-eval a CSP-ből — a runtime el sem indul.

Ha elakadsz, ezt küldd a Lupiannak

• A teljes .riv URL-t (hogy curl -I-val ellenőrizhessük).
• Az oldal URL-jét.
• Egy képet a Network fülről a .riv válaszfejléceivel.
• A konzolhibákat.
• A teljes lista: Kérj segítséget a Lupiantól.

Kapcsolódó

• Nem töltődik be az animáció
• Beágyazási lehetőségek
• Rive asset loading API: rive.app/docs