3. Šablon i build
Poglavlje 3

Šablon i build

potok prima jedan HTML fajl. Ovo poglavlje pokazuje kako ga šablon pravi iz običnog Vite projekta i šta iz toga sledi za tvoj kod: zašto nema top-level await-a, odakle dolazi potok i zašto se <head> gubi.

3.1. Od projekta do jednog fajla

npm run build pokreće tsc, pa običan vite build, koji u dist/ piše index.html i fajlove u dist/assets. Posle toga dodatak potokBuildPlugin iz vite.config.ts sve spaja u jedan fajl, dist/potok-build.html.

index.html, src/main.ts i src/style.css idu u vite build; potokBuildPlugin od rezultata pravi dist/potok-build.html, koji se otprema u opis grupe i radi u iframe-u. index.html src/main.ts src/style.css ovo menjaš tsc + vite build potokBuild- Plugin potok-build.html Opis grupe iframe u potok-u Otpremi ZIP body + CSS + JS u jedan fajl
Build: tri fajla koja menjaš → tsc i vite build → potokBuildPlugin → jedan HTML fajl koji se otprema u opis.

Dodatak radi samo pri build-u (apply: 'build'), u koraku writeBundle. Iz dist/index.html:

3.2. Šta je u potok-build.html

Fajl nema <html>, <head> ni <body>: to je sadržaj koji potok stavlja u #group-panel-description. Skraćeno:

<!-- style goes here -->
<style>/* sav CSS */</style>
<!-- html goes here -->
<!-- sadržaj <body> iz index.html -->
<!-- script wrapper -->
<script type="module">
/*! The packages bundled into this app and their licenses: … */
(()=>{
  const interval = setInterval(() => {
    const host = document.querySelector("#group-panel-description")
    if (host && host.potok &&host.potok.insertGroupValue) {
      clearInterval(interval);
      const potok = host.potok;
      potok.eventListenerOptions = {signal: potok.abortController.signal};
      // app code goes here: ceo tvoj bundle
    }
  }, 300);
})();
</script>

Wrapper na svakih 300 ms proverava da li je potok postavio legacy API na #group-panel-description. Kad jeste, pravi lokalnu promenljivu potok, postavlja joj eventListenerOptions i tek tada izvršava tvoj kod.

Pošto su CSS i JS ubačeni u sam HTML, build u njima menja </script i </style u <\/script i <\/style (escapeInlineContent), da string u kodu ne bi zatvorio tag pre vremena.

3.3. Šta iz toga sledi

Tvoj kod je telo obične funkcije
Bundle stoji unutar () => { … }, a ne na vrhu modula. Zato top-level await u build-u postaje sintaksna greška i aplikacija se ne pokreće, iako su tsc i vite build prošli (poglavlje 4).
potok je lokalna promenljiva
U build-u ga daje wrapper, a u dev-u ga postavlja dev mock na globalThis. Zato se potok ne uvozi; iz src/potok.ts se uvoze samo tipovi, sa import type. declare global u src/potok.ts govori TypeScript-u da potok postoji (PotokApi), a window.potok je PotokSdk.
<head> iz index.html se ne prenosi
U build ulazi samo sadržaj <body>. <title>, meta tagovi i sve ostalo iz <head> se gube; CSS iz <link> ne, jer ga dodatak posebno čita i ubacuje.
Objavljuje se samo jedan fajl
Dodatak čita samo CSS i JS na koje index.html upućuje. Dinamički import(), chunk-ovi, fajlovi iz public/ i slike iz dist/assets ne ulaze u potok-build.html (poglavlje 4).
Napomena

potok iz opisa aplikacije čita <meta name="description"> i taj tekst daje kao app_description podgrupe u listSubgroups (poglavlje 11). Pošto build prenosi samo <body>, takav meta tag stavi na početak <body> u index.html, ne u <head>.

3.4. index.html

U dev-u je index.html obična Vite stranica: <head> učitava /src/style.css, a na kraju <body> je <script src="/src/main.ts" type="module">. U build-u od nje ostaje sadržaj <body>, a skripta i CSS se ubacuju inline.

<body>
  <div class="app-main relative h-dvh cursor-crosshair select-none overflow-hidden">
    <p class="pointer-events-none absolute top-4 left-4 text-sm opacity-60">Klikni bilo gde da postaviš svoj avatar.</p>
    <p class="app-status pointer-events-none absolute bottom-4 left-4 text-sm text-red-600"></p>
  </div>
  <script src="/src/main.ts" type="module"></script>
</body>

Demo traži svoje elemente po klasama (.app-main, .app-status) sa document.querySelector. Tvoj HTML u potok-u stoji unutar #group-panel-description, pa taj id ne koristi za svoje elemente.

3.5. Stil: Tailwind, daisyUI i fajlovi

@import "tailwindcss";

/* The dev mock is not in the build, but Tailwind would take its words for
   classes and add them to the build's CSS. */
@source not "./potok-dev.ts";
/* The API's types, whose words in comments would become classes. */
@source not "./potok.ts";
Dev mock

Dev mock nema CSS stranice. Klase btn, table i ostale daisyUI klase u npm run dev izgledaju kao običan HTML; pravi izgled se vidi tek u potok-u.

3.6. Licence putuju sa build-om

Vite piše spisak paketa iz node_modules koje pakuje u aplikaciju, sa punim tekstom licence (build.license, fajl .vite/license.json). Dodatak taj spisak stavlja na vrh skripte, kao jedan komentar /*! The packages bundled into this app and their licenses: … */. Ako aplikacija ne pakuje nijedan paket, komentara nema.

Komentare sa @license ili /*! iz samog koda build zadržava (output.comments.legal), iako ih Vite pri minifikaciji inače briše.

Važno

Kod koji ulazi bez napomene o licenci dobija je u tvom kodu ili CSS-u. daisyUI-jev CSS iz Tailwind dodatka stiže bez nje, pa aplikacija sa daisyUI-jem ima /*! daisyUI | MIT License | https://daisyui.com */ u src/style.css.

3.7. TypeScript

tsconfig.json je strog: strict, noUnusedLocals, noUnusedParameters, erasableSyntaxOnly i verbatimModuleSyntax. Posledice koje primetiš odmah:

Oblik podataka zadaj generikom, pa TypeScript zna šta je u data:

import type { PotokValue } from './potok';

type Item = { name: string; count: number };

function label(value: PotokValue<Item>): string {
  return value.data ? `${value.data.name}: ${value.data.count}` : '';
}

async function load() {
  const reply = await potok.getGroupDataValues<Item>();
  if (!reply.ok) return console.error(reply.error);

  const total = reply.values.reduce((sum, v) => sum + (v.data?.count ?? 0), 0);
  console.log(total, reply.values.map(label));
}

void load();