Knižnice a CDN v projekte pre prehliadač

Požiadate Claude Code, aby vytvoril šach v prehliadači. Otvoríte stránku: šachovnica je na mieste, figúrky sú rozostavené a pešiak poslušne nasleduje myš. Dá sa hrať. Na skúšku ho však potiahnete rovno o tri polia dopredu - a tam aj zostane. Potom skúsite dvakrát za sebou zahrať čiernymi. Stránka ani tentoraz nič nenamieta.

Pred týmito dvoma ťahmi vyzeral projekt takmer hotový. Teraz sa ukáže, že to hlavné ešte nefunguje: pravidlá nikto nekontroluje. Môžete požiadať agenta, aby taký ťah pešiakom zakázal. Potom však treba vyriešiť poradie ťahov, šach, rošádu aj premenu pešiaka. Po každej oprave zostáva otázka: na ktorú podmienku ste ešte zabudli?

V tejto chvíli sa oplatí zastaviť a pohľadať hotový kód na túto úlohu. Šachové pravidlá už implementuje knižnica chess.js. Môžete jej odovzdať ťah a dostať výsledok kontroly. Vlastný kód potom zodpovedá za zrozumiteľné prepojenie: prevezme ťah zo šachovnice, skontroluje ho cez knižnicu a zobrazí správne rozostavenie figúrok.

Zostáva dostať knižnicu do prehliadača a zapojiť ju do stránky. Jednou z možností je načítať ju cez odkaz z CDN. Pozrime sa, ako to funguje a prečo odkaz v kóde ešte neznamená, že pešiak už nemôže chodiť kamkoľvek.

Čo robí knižnica

Knižnica je cudzí kód, ktorý si pridáte do projektu, aby ste nemuseli znova písať niečo, čo už niekto napísal. chess.js je presne taký prípad: pozná pohyb každej figúrky, šach aj rošádu, vie vypísať všetky povolené ťahy z aktuálnej pozície a zistiť, či sa partia skončila.

A tu sa ľahko dostanete do pasce: pripojíte knižnicu a čakáte, že hra začne fungovať. Nezačne. Knižnica si pamätá pravidlá a aktuálnu pozíciu partie, nič nekreslí a ani netuší, že na stránke je šachovnica.

Pozrite sa, čo sa deje pri bežnom ťahu. Potiahnete pešiaka z e2 rovno na e5. Rozhranie zaznamená presunutie, prepojovací kód sa knižnice opýta: "Je tento ťah povolený?" Knižnica odpovie "nie" a prepojovací kód vráti figúrku späť na e2. Ak túto otázku nikto nepoloží, pešiak pokojne zostane na e5: stránke nič nebráni, aby ho tam vykreslila.

Obe vetvy sa končia rovnakou akciou: prepojovací kód zobrazí pozíciu z knižnice. Po povolenom ťahu je už nová, po nepovolenom zostane pôvodná, preto sa figúrka vráti na svoje miesto.

Z toho vyplýva, ako formulovať zadanie. Požiadavku "pripoj chess.js" možno splniť doslova - pribudne riadok na načítanie a hotovo. Požiadajte radšej o celé prepojenie: ťah zo šachovnice sa odovzdá knižnici, jej odpoveď rozhodne, či sa figúrka posunie, a pozícia po ťahu sa berie zo stavu knižnice, nie z miesta, kde ste pustili myš.

Ako prehliadač získava kód cez CDN

Súbor knižnice treba odniekiaľ získať. Môžete si ho stiahnuť a uložiť vedľa stránky alebo v kóde stránky uviesť odkaz na súbor v externej službe. Na to sa často používa CDN (Content Delivery Network, sieť na doručovanie obsahu). Je to sieť serverov, ktoré poskytujú súbory používateľom z rôznych miest. Cez CDN sa doručujú napríklad obrázky, štýly a JavaScriptové knižnice. V našom príklade súbor knižnice poskytuje služba jsDelivr.

Keď otvoríte stránku, prehliadač prečíta jej kód a narazí na odkaz na knižnicu. Vyžiada si súbor z tejto adresy, načíta ho a potom spustí kód stránky, ktorý knižnicu používa. Knižnica beží v prehliadači používateľa. CDN doručí jej kód; kontrola šachových ťahov už prebieha na vašom zariadení.

Rámček na schéme oddeľuje prehliadač od externej služby. Po načítaní sa knižnica nachádza priamo na stránke a prepojovací kód k nej pristupuje tam. Každý ťah na CDN posielať nemusíte.

Pripojenie knižnice chess.js vyzerá takto:

<script type="module">
  import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'

  const chess = new Chess()
  console.log(chess.fen())
  // rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>

Dôležité sú tu tri detaily. Prvým je type="module". Knižnica sa načíta ako ES modul a triedu Chess z nej získate iba pomocou importu; bežná značka <script src="..."> tento súbor nespracuje - zlyhá na export vnútri súboru. Niektoré knižnice majú aj staršiu podobu bez modulov: tam stačí obyčajná značka a na stránke sa sama objaví globálna premenná. chess.js takú zostavu nemá, takže existuje len tento spôsob.

Druhým detailom je číslo verzie priamo v adrese, chess.js@1.4.0. Spôsob pripojenia a názvy metód berte z dokumentácie práve tej verzie, ktorá je v odkaze. Adresa bez čísla skôr či neskôr povedie k inému súboru a kód napísaný podľa starej dokumentácie prestane fungovať.

A tretím, najmenej nápadným detailom je prípona /+esm na konci adresy. Nie je to ozdoba, ale požiadavka, aby CDN zostavilo súbor ako modul: bez nej príde z rovnakej adresy iná zostava a import nič nenájde.

Skontrolovať, či sa knižnica naozaj načítala, môžete aj bez toho, aby ste dokončili celú hru - do toho istého <script type="module"> dopíšte pár riadkov a otvorte konzolu prehliadača (karta Console v nástrojoch pre vývojárov, F12 alebo Ctrl+Shift+I):

// biely pešiak nemôže ísť z e2 rovno na e5
try {
  chess.move('e5')
} catch (error) {
  console.log('ťah zamietnutý:', error.message) // Invalid move: e5
}

chess.move('e4')          // tento ťah knižnica prijme
console.log(chess.turn()) // b, na ťahu sú čierni

Počiatočná pozícia v konzole, zamietnutý ťah a čierni na ťahu po e4 znamenajú, že súbor dorazil a pravidlá fungujú. Zostáva už len prepojiť ich so šachovnicou.

A ešte jedna poznámka, aby nevznikli mylné predstavy. CDN neodstraňuje závislosť od siete. Prehliadač môže súbor znova použiť z cache, teda z vlastnej uloženej kópie, takže ho nemusí pri každom otvorení stránky sťahovať znova. Ak však nemá vhodnú kópiu a CDN nie je dostupné, knižnica sa nenačíta a hra nebude môcť používať jej pravidlá.

Ako to funguje v spojení s Claude Code

Požiadavka "pripoj knižnicu cez CDN" necháva agentovi viacero rozhodnutí: odkiaľ získať súbor, ktorú verziu vybrať, ako ju načítať na tejto stránke a ako potvrdiť výsledok. Lepšie je uviesť tieto rozhodnutia priamo v zadaní. Nižšie sú prompty pre rôzne situácie; nemusíte ich posielať všetky za sebou.

Vyberte odkaz na pripojenie

Ak agent navrhne knižnicu, najprv ho požiadajte, aby zistil, ako ju pripojiť vo vašom projekte. Budete tak mať konkrétnu adresu aj vysvetlenie, odkiaľ sa vzala.

Pozri sa, ako je vytvorená moja stránka a či už používa chess.js.
V dokumentácii knižnice a služby jsDelivr nájdi spôsob načítania cez CDN,
ktorý je vhodný pre prehliadač. Navrhni URL s konkrétnou verziou a vysvetli
jednotlivé časti adresy. Pridaj odkazy na dokumentáciu. Kód zatiaľ nemeň.
Ak sa dokumentáciu nepodarilo skontrolovať, povedz to.

V odpovedi hľadajte číslo verzie, spôsob pripojenia a dôvod výberu. Samotné "tu je funkčný odkaz" nestačí: neviete z toho, či agent adresu porovnal s dokumentáciou a či sa súbor hodí pre vašu stránku.

Prepojte knižnicu so šachovnicou

Keď už máte adresu, zadajte agentovi úlohu s viditeľným výsledkom. Pri jednoduchej HTML stránke môžete rovno uviesť, že chcete zachovať súčasný spôsob spúšťania.

Pripoj chess.js cez vybranú CDN adresu s pevne určenou verziou.
Zachovaj súčasný spôsob spúšťania stránky. Prepoj knižnicu
so šachovnicou: odovzdávaj jej každý ťah a zobrazuj pozíciu z jej stavu.
Pri nepovolenom ťahu vráť figúrku na pôvodné pole.
Ukáž, kde si pripojenie pridal a kde spracúvaš odpoveď knižnice.

Ide o dva samostatné výsledky: prehliadač získal knižnicu a ťahy na šachovnici sa začali riadiť jej pravidlami. Keď požiadate agenta, aby ukázal obe miesta v kóde, uvidíte, čo presne pridal.

Overte výsledok v prehliadači

Odkaz v HTML potvrdzuje len to, že sa upravil súbor. Nasledujúce zadanie pomôže overiť samotné načítanie aj správanie hry.

Otvor stránku a na karte Network v nástrojoch pre vývojárov
skontroluj, či sa načítala chess.js. V Console skontroluj chyby.
Potom z počiatočnej pozície skús e2-e5: ťah má byť zamietnutý
a pešiak má zostať na e2. Následne zahraj e2-e4: ťah má prejsť
a na ťahu majú byť čierni. Oznám, čo si pozoroval v každom kroku.
Ak nemáš prístup k prehliadaču, uveď krátky postup kontroly
a povedz, že si ho sám nevyskúšal.

Na karte Network vidno sieťové požiadavky stránky, v Console správy a chyby jej kódu. Ak sa súbor načítal, ale pešiak aj tak dôjde na e5, príčinu treba hľadať v spracovaní ťahu. Samotná výmena odkazu CDN toto prepojenie neopraví.

Vyriešte chybu pri načítaní

Ak sa niečo pokazí, pošlite agentovi presný text chyby z Console a adresu neúspešnej požiadavky z Network. Môže tak overiť konkrétnu príčinu namiesto skúšania rôznych odkazov.

Po pripojení knižnice stránka zobrazuje chybu.
Text z Console: [vložte celé hlásenie].
URL a výsledok požiadavky v Network: [vložte adresu a stav].
Skontroluj, či je súbor dostupný, či jeho formát vyhovuje nášmu importu
a či sa názvy v kóde zhodujú s dokumentáciou vybranej verzie.
Najprv na základe týchto údajov pomenuj príčinu, potom urob minimálnu
opravu a zopakuj kontrolu. Nemeň naraz CDN, verziu aj kód hry.

Text v hranatých zátvorkách nahraďte vlastnými údajmi. Ak sa v Network vôbec nenachádza požiadavka na knižnicu, napíšte to - aj to je užitočná stopa. Po oprave zopakujte kontrolu oboch ťahov, aby ste si overili, že celé prepojenie funguje.

Počítajte s nedostupnosťou CDN

Ak sa knižnica nenačíta, aktívna šachovnica môže vyvolať dojem, že sa stále dá hrať. Požiadajte agenta, aby bol tento stav pre používateľa zrozumiteľný.

Ošetri situáciu, keď sa chess.js nepodarí načítať z CDN.
Kým knižnica nie je pripravená, nedovoľ ťahy. Pri chybe zobraz
zrozumiteľné hlásenie a možnosť obnoviť stránku.
Over správanie pri zablokovanej požiadavke na CDN a potom po
zrušení blokovania. Nezabudni na cache: samotné odpojenie siete môže
nechať dostupnú už predtým načítanú kópiu. Opíš, ako si zlyhanie overil.

Túto kontrolu je jednoduchšie urobiť oddelene od bežnej partie. Mali by ste vidieť dva jasné stavy: knižnica je dostupná a ťahy sa kontrolujú; načítanie zlyhalo a stránka vysvetľuje, prečo zatiaľ nemožno hrať.