Pravila koja build ne hvata
Kršenje ovih pravila obično prolazi npm run dev, pa i npm run build, a aplikacija pukne tek u potok-u. Svako pravilo ima primer koji ne radi, primer koji radi i razlog.
Dev mock i build nisu potok: u dev-u nema wrapper-a, iframe-a ni servera, a tsc proverava tipove, ne okruženje. Ova pravila pokrivaju upravo tu razliku.
4.1. Bez top-level await
Wrapper ubacuje bundle u običnu funkciju (poglavlje 3). await van async funkcije je tada sintaksna greška, i ceo skript se ne pokreće. U dev-u main.ts radi kao ES modul, gde je top-level await dozvoljen, a tsc i vite build ga takođe prihvataju.
// src/main.ts
const reply = await window.potok.listValues();
if (reply.ok) render(reply.values);
async function load() {
const reply = await window.potok.listValues();
if (!reply.ok) return console.error(reply.error);
console.log(reply.values);
}
void load();
Jedini izuzetak je blok if (import.meta.env.DEV) na vrhu src/main.ts: on uvozi dev mock sa await import('./potok-dev'), a build ga izbacuje, pa u potok-build.html ne stigne.
4.2. Ceo JS u jednom fajlu
Objavljuje se samo potok-build.html. Dinamički import() pravi poseban chunk u dist/assets, koji dodatak ne ubacuje u fajl, pa ga u potok-u nema. Uvozi sve statički, na vrhu modula.
button.addEventListener('click', async () => {
const { drawChart } = await import('./chart'); // chunk koji se ne objavljuje
drawChart();
}, potok.eventListenerOptions);
import { drawChart } from './chart';
button.addEventListener('click', () => drawChart(), potok.eventListenerOptions);
4.3. Slike i fontovi inline ili sa apsolutnog URL-a
public/ i dist/assets se ne objavljuju. Vite sam ubacuje inline samo fajlove manje od 4 KB; veći ostaju u dist/assets, a u potok-u ih nema. U dev-u Vite servira sve, pa slika tamo radi.
<img src="/logo.png" alt="Logo"> <!-- iz public/: u potok-u ne postoji -->
<!-- SVG u HTML-u, data URL ili apsolutan URL -->
<svg viewBox="0 0 24 24" class="size-6"><path d="M4 12h16"/></svg>
<img src="data:image/png;base64,iVBORw0KGgo…" alt="Logo">
<img src="https://primer.rs/logo.png" alt="Logo">
4.4. potok se ne uvozi
U build-u potok daje wrapper kao lokalnu promenljivu, a u dev-u ga postavlja dev mock. src/potok.ts ima samo tipove i declare global, pa se iz njega uvoze samo tipovi, sa import type.
import { installDevPotok } from './potok-dev'; // dev mock bi ušao u build
installDevPotok();
import type { PotokValue } from './potok';
if (import.meta.env.DEV) {
const { installDevPotok } = await import('./potok-dev');
installDevPotok();
}
Statički uvoz ./potok-dev bi ugurao ceo dev mock (preko 3000 linija) u build. Uvoz u DEV bloku build izbacuje.
4.5. potok i window.potok su dva API-ja
potok je legacy (insertGroupValue, getGroupDataValues…), a window.potok noviji SDK (insertValue, listValues…). Dev mock postavlja potok kao jedan objekat sa oba API-ja ({ ...sdk, ...legacy }), a u potok-u su to dva objekta.
// radi u dev-u, u potok-u: TypeError: potok.insertValue is not a function
await (potok as any).insertValue({ done: true });
async function markDone() {
const reply = await window.potok.insertValue({ done: true });
if (!reply.ok) console.error(reply.error);
}
void markDone();
Tipovi poštuju podelu: PotokApi nema insertValue, pa potok.insertValue ne prolazi tsc. Greška u potok-u nastaje tek kad se tipovi zaobiđu (any, // @ts-ignore) ili kad se kod piše u čistom JS-u.
4.6. Slušaoci dobijaju potok.eventListenerOptions
Wrapper postavlja potok.eventListenerOptions = {signal: potok.abortController.signal}. Kad se aplikacija ponovo učita, abortController uklanja svakog slušaoca koji je dobio taj signal. Slušalac bez njega ostaje, pa posle ponovnog učitavanja isti događaj može da obradi dvaput.
document.addEventListener('keydown', onKey);
function onKey(event: KeyboardEvent) {
if (event.key === 'Escape') console.log('close');
}
document.addEventListener('keydown', onKey, potok.eventListenerOptions);
window.addEventListener('resize', () => console.log('resize'), potok.eventListenerOptions);
Legacy potok uz to ima potok.el, sam element #group-panel-description u kome stoji tvoj HTML, i potok.abortController, čiji je signal u eventListenerOptions.
Slušaoci SDK-a (onNewValue, onValues, onPollChange…) vraćaju funkciju za odjavu; pozovi je kad ti slušalac više ne treba.
4.7. data je uvek JSON objekat
Server odbija niz, broj ili tekst greškom invalid_value. tsc to ne hvata: insertValue<T extends object> prima i niz, jer je niz u TypeScript-u objekat. Dev mock odbija isto što i server, pa se greška vidi već u npm run dev, ali samo ako proveriš reply.ok.
await window.potok.insertValue([1, 2, 3]); // invalid_value
await potok.insertGroupValue(JSON.stringify('zdravo')); // invalid_value
async function save(scores: number[]) {
const reply = await window.potok.insertValue({ scores });
if (!reply.ok) console.error(reply.error);
}
void save([1, 2, 3]);
4.8. Vrednosti se uglavnom samo dodaju
Legacy potok nema izmenu ni brisanje. U window.potok autor menja svoju vrednost (updateValue) samo u kolekciji čije pravilo ima edit_own, a brišu samo urednici (deleteValue, deleteValues). Zato stanje računaj iz svih vrednosti: na primer poslednja vrednost po korisniku, kao u demou, ili zbir (poglavlje 5).
4.9. updateGroupDescription menja samu aplikaciju
Opis je HTML aplikacije. updateGroupDescription (i updateDescription u window.potok) ga zamenjuje, pa se aplikacija ponovo pokreće sa novim kodom. Menja samo opis te aplikacije, podrazumevani ili alternativni, i traži pravo na izmenu grupe. Ne koristi ga za čuvanje stanja: za to su vrednosti, kolekcije i lična memorija (poglavlje 8).
U dev mock-u updateGroupDescription samo zapamti opis, a aplikacija nastavlja da radi. U potok-u bi se ponovo učitala.
4.10. Proveri reply.ok
4.11. Ostalo iz „Pravila i zamki“
- Limiti: najviše 200 vrednosti po strani i 5000 za
getGroupDataValues()bezlimit; najviše 30 upisa zaredom, a limit se obnavlja tokom 10 s (poglavlje 6). - Prava: upis traži članstvo u grupi, a izmena opisa pravo na izmenu grupe (poglavlje 6).
- Gost samo čita: umesto dugmeta koje mu ne radi pokaži „Prijavi se“ sa
openLogin()(poglavlje 6). - Licence putuju sa build-om; daisyUI napomenu dodaješ sam (poglavlje 3).
- Tailwind ne čita dev mock ni tipove (
@source not, poglavlje 3).