Архіпелагі, які можна перзумаваць на Bun: урокі дизайну з франкаменту кераміки
Як фреймворк, які спачатку оріѐнтуюцца на сервер, выкарыстоўвае HTML як стандартны формат, обмежвае дзейнасць JavaScript на аддзеленыя часткі коду, якія можна запускаць паэтапна, а таксама керуе статычным экспортом, падзеямі бягу, правіламі безпекі та процесам развяртання.
Большая частка сторанцоў у інтэрнете ўключае толькі кантэнт з калькамі інтэрактыўных элементаў, пры тым што домінантныя модэлі развіцця адправляюць цэлы сторанец у браузер як JavaScript-прыемлівасць. Stoneware – молады фрэймворк на TypeScript з адкрытым кодам, створаны на базе Bun – выходзіць з працоўнае прыпуску: HTML – гэта тое, што браузер отрымае за замовчаннем, і компонент должен явна падтрымаць гэта рашэнне, перш чым для яго будзе адправлены JavaScript. Аналіз його дизайну ўжоць цікавы спосаб разумець такія аспекты, як статычны экспорт, можлівасць паўторнага запуску, а таксама менш зрозумелыя часткі роботы з фрэймворкамі, такія як паведамленні пра абераннях, правілы безпекі і пакаванне для развяртання. У канцы вы должны змагчымаць адначасна адначасна вярнуцца, калі архітектура, заснованая на сервере і прыемлівасцях, падходзіць вашам проекту, і якія аберанні трэба старацца ужоць, якшы вы хочаце ёю скорыстацца.
Чаму сторанец з кантэнтам не павінен стаць прыемлівасцю
Уявіце сабэчную сторонку товара. У яе ёсць заглавле, фота, апісанне, спіс характэрыстыкаў, цена, супаўнае абладнанне, атказы і можлівасці навігацыі па сайте. З усьго гэтага, можабы, толькі два элемента насправды реагуюць на корыстніка: меню для мобайльных прыстроёў і кнопка «Да кошчанкі». Усе інше — статычны контэнт, які сервер вядома як выдаваць.
Падход, калі кантэнт генеруецца на кліянцы, або падход з цэлым заправленым кантэнтом, таксама вымагае, каб браузер завантажыў, распакаваў і выканаў код, який представляе цэлую сторонку, толькі каб гэтыя два элементы моглі працаваць. Пры падходзе, калі сервер ёсць першым элементам, пытанне простае: што, як браузер отрымае толькі код для тых частак, якія яму патрэбны?
Ментальная модель: HTML плюс адзеленыя часткі
Архітектура дзельніцяе сторанку на два типы тэрытарыю. Большая частка з яе — HTML, які генеруецца на серверы. Інтэрактыўныя элементы стаюць «островамі» — малыми самастойнымі регіонамі, якія маюць свой сабе JavaScript. І тое, і другое знаходзіцца ў однам дакументе ў браузеры.
Web page
│
┌───────────┴───────────┐
│ │
HTML Islands
│ │
Server rendered JavaScript
│ │
└───────────┬───────────┘
│
Browser
Ключовы наследк — інтэрактыўнасць больш не вымагае перадавання цэлай прыкладнай програмы. Чым урабіць адны элемент інтэрактыўным, тым толькі код гэтага элемента становіцься неабходным, а не код сторанкі.
Развіць на Bun замест асамблявання інструментальнага комплексу
Выбір Bun не означае, што Node.js ўжо застарэў. Node мае вялічзеную экасыстэму і выкарыстоўваецца ў вельмі большай частцы продакшн-проектаў на JavaScript, і ён застаецца абліковым рантаймам. Цікавае тое, што зменшыцца, калі фрэймворк будзе спроектаваны навакол рантайму, які вже мае неабходныя інструменты для большасці проектаў.
Bun адаптавае рантайм JavaScript разам з калектарным каштоўнікам, інструментам для зборкі коду і адпаведным інструментам для тэставання. Для создатэў фреймворках гэта пазбавляе іх большай часткі додатковых налаштаванняў. Уместо таго, каб фреймворк стаў частынай Node, а пасля — калектарны каштоўнік, окремы інструмент для зборкі коду і окремы інструмент для тэставання, такія рашэнні дазволяюць расследзіваць усе гэта як адну цяжыстую базу.
Bun
│
┌────────────┼────────────┐
│ │ │
Runtime Tooling Testing
│ │ │
└────────────┼────────────┘
↓
Stoneware
Важна чыткая дзеяння: Bun — это платформа, а Stoneware — фреймворк, який працюе на ёй. Якщо хочаце болей шырокага порэвання самых рантаймов, адзірніце порэванне Node.js, Deno і Bun.
HTML адначасова, з усім серйозна
Серверная обработка канваса існуе вже давно, таму фраза «обрабоць HTML на серверы» здаецца нечамусціма. Сильнейшая практыка, яка стоіць за Stoneware, заключаецца у тым, што сервер павінен стварыць справжняя, корыстная HTML-тэкстаўеранцю прычым, каб браузер не мусіў ніч знаць пра сам аплікэшн.
Возьмім компанент, які адображае тавар з заглавлём і цэнай.
<ProductCard
title="MacBook Pro"
price={1999}
/>
Для гэтага компанента не трэба, каб браузер зберагаў яго модэль на JavaScript. Сервер можа ператворыць його ў простую маркапт-тэкстаўеранцю:
<div class="product-card">
<h2>MacBook Pro</h2>
<span>$1999</span>
</div>
Гэты выход уже ўжо готавы. Людзі можаць яго прачытаць, роўеры пошуковых сістэм можаць яго індексаваць, а браузер можа яго негайна адобразіць. У самай доставцы кантэнту не ўчаствуюць жадныя скрыпты.
Явнае выбіранне JavaScript
Тепер дадам кнопку каляскі. На адзін з таварных картак, яна павінна реагаваць на клікі, апдэйтаваць стан і, верагатна, вясці са API.
<AddToCart product={product} />
У гэтым компаненте адгукуюцца дзеянні з баку кліента, таму ён стае «островам». Рэштка сторанкі застаецца у формате HTML, і гэта сторанка выглядае так:
Product page
│
├── Product title HTML
├── Product description HTML
├── Product image HTML
├── Product specifications HTML
│
└── Add to cart JavaScript island
Старанка не ўсунутая ад JavaScript. У яй выкорыстоўваюцца скрыпты выбаркова, прычаму да выбору прыходзяць па компанентам, а не па всій старанцы. Гэта разлік мае значэнне, таму што ён дазволяе застаўляць стандартны варыянт дышэўкім, а кожны фрагмент коду стае відчутным, свядомым выборам.
Дзе знаходзіцца межа «острова»
Астровыя знакі выдзеляюць межу межу тэксту, які адрасаваецца на серверы, і функцыйнасцю, якая выканана на кліенты. Сайт дакументацыі чыста показвае гэты прынцып. Тэкст статыі, загаловкі, прыклады коду, адпраўкі, звязкі, навігацыя і футэр — усё гэта ўскладненне. Лічнае колькасць функцыйяй ёсць практычна інтэракtyвныя: пошук, пераключальнік тэм, кнопкі копіювання ў буфер копіювання на блаках коду і, можабыта, розгорнутая дрэва навігацыі.
Documentation page
│
├── Article ─────────────── SSR
├── Code blocks ─────────── SSR
├── Images ──────────────── SSR
├── Navigation ──────────── SSR
│
├── Search ──────────────── Island
├── Theme switcher ──────── Island
└── Copy button ─────────── Island
Такія сторанкі, якія пераважна складаюцца з ускладнення і толькі лічнае колькасць інтэракtyвных регіонаў, якраз і є метайю разрабоцы фрэймворку.
Гідратацыя проты возможнасці продажу
Справядлівая працоўка — гэта всё проста SSR. Часткова так: сервер адрасаваець HTML. Разлік заключаецца у тым, што выдзейваецца пасля таго, як гэты HTML прыбывае.
У класычнай гідратацыі парадокс працоўкае приблізна так:
- сервер адрасаваець HTML;
- браузер завантажвае JavaScript аплікацыі;
Браузер у падсумку перабудавае прыкладненне, чыя выхідны даны ён вядома яўляе. З точкі зору пользователя гэта проста дапаможны процес: пікселі вядома ўжо былі на экране.
У замену гліняная кераміка праектуецца так, што включае адзеленыя регіоны, якія можна практычна запускаць знову. Сервер адправляе HTML разам з усім станом, які патрэбен гэтым інтэракtywnым регіонам, а браузер працюе з тыми регіонамі, дзе сервер завершыў свою роботу, а не перывыканае всю сторунку, каб знову з’явіць гэты стан. Мета — запобець таму, каб маленькія інтэракtywnыя регіоны змусвалі перабудаваць всю сторунку.
Іншая мета оптымізацыі
Магчымасць практыкавання перакрашвае пытанне пра выкарыстоўнасць. Уместо таго, каб спытацца, як прышвыдзіць процес інтеграцыі всіх элементаў, трэба спытацца, сколькі роботы браузера можна абэцьна ухіліцца. Навантажэнне пераходзіць з „HTML плюс усі JavaScript-коды прыложэння плюс процес інтеграцыі“ на „HTML плюс толькі код, неабходны для взаімадзеяння, пры чым продовжэнне роботы ведзецца з стану, вырахаванага на серверы“. Для сайтаў з великім колькам контэнту гэта часта ўзначныяй перавагай, чым будзь-якая оптымаізацыя процесу інтеграцыі.
Якщо вы працуеце з React, той самы падтрымкі стоіць за сервернымі компанентамі; архітектура, якая лежыць у основе выкарыстоўвання серверных компанентаў без стварэння бандлу раскрывае гэты падход і дае корыстныя порэванні.
Падход, у яком сервер ёсць прыорітэтом, не значыць выкарыстоўвання толькі сервера
Нічыя з гэтых пунктаў не ўтварае аргумента проты кліентскіх застосоў. Спрацоўныя редактары, інструменты дизайна, гэмы ў браузеры і складныя інтэрактывныя застосункі з дадзенням маюць абліковыя разныя патрабаванні, і большасць іх складовых ў сваей сутнасі ёсць інтэрактывнымі. Архітектура нацёлена на працоўную частку спектру: сторанкі, дзе большасць кантэнту па свайбе адрасаваецца на сервер, а інтэраакцыя ёсць выключэнням.
Статычны экспорт выліваецца з той жа ідэі
Якщо HTML ёсць стандартам, то наступным логічным пытаннем є, чаму воўсе трэба запускать сервер для сторанак, якія за кожны запыт не зменяюцца. Stoneware можа экспораваць застосунак у вачынку статычных файлоў і перадаць іх CDN.
Stoneware application
│
▼
export
│
▼
dist/
│
▼
CDN
Дакументацыю, сторанкі маркетынгу і каталогі продуктав частаюць ствараць заздалегідь і выдаць яе безпосередна з сервера. Маршруты, які практычна патрабуюць логіки на кожны запит, можа застацца серверная. Адзін з прыёмоў — пераклад маршруту з статычнага у серверна выдачу не трэбуе змены цэлага праграмаванняя моделі для всей аплікацыі.
Дынамічныя маршруты патрабуюць явнага спісу шляхоў
Статычны экспорт становіцца складнейшым, калі маршрут мае параметры. Маршрут у формате /products/[sku] у прынцыпе можа падходзіць да несканчатлівага кола URL-адрэс, таму экспортар не можа здагадацца, якія сторанкі трэба стварыць. Таму фреймворк прасіць маршрут перыябраць іх:
export function staticPaths() {
return products.map(product => ({
sku: product.sku
}));
}
За дапамою гэтага спісу экспортар пішыць справжній HTML-файл для кожнага вядомага SKU, напрыклад dist/products/laptop-1/index.html. Сюды дизайн фрэймворка выходзіць за межы простага атрыбутавання JSX: фрэймворк павінен разумець, як маршруты, даныя, крок будовы і цэль развёрткі взаінасоедынуюць. Практычны краевы случай, які трэба узгадаць, — гэта калі дынамічны маршрут узагалі не мае staticPaths(); фрэймворк павінен альбо яскрава адзначыць адмову, альбо заставіць гэты маршрут обрабатвацца на сервере, а тыха ўпусканне яго — гэта найгоршы варыянт.
Паведамлення пра адмовы ўскладневаюць роботу рэндерара
У сваім сутнасці рэндэрар берае компанент і стварае HTML. Складнасць створяе вельмі вялікая разнаўтнеча дзецэрых элементаў і атрыбутаў, з якімі ён должен справляцца: текстовыя і числавыя значэння, масівы і null, элементы і вкладаныя компаненты, сігналы і атрыбуты, выкліканыя падчас обработкі бяды, асінхронная работа і, неабходна, значэнняя, якія нельга рэндэрацыя.
Пашчастай памылкай є напісанне <span>{product}</span> калі мавацца на увазе <span>{product.name}</span>. Узвычайленая паведамленне „Нельга рэндэрацыя значэння типу об’ект“ майже нічога не паведамляе пра тое, дзе шукать прычыну. Stoneware замест таго описвае сама проблемная значэння:
Cannot render a plain object with keys: id, title, price.
і пасля таго прыводзіце шлях да компанента, які прынёс гэту проблему:
in <span>
in <Price>
in <ProductCard>
in <Home>
Співстаўленне ключоў об’екта падказвае власць, яку вы, верагодна, мелі на увазе, а след з компанентаў вядзе да точнага файла, які трэба ачыняць. Фреймворк оцінюецца не толькі за успешным варыянтом роботы, але і за тым, насколькі шыбкаа ён дапамагае выйсці з нуспешных ситуацыяў.
Калі мікротэст скрывае рэальныя витраты
Сбор такога следу з компанентаў спачатку значыў обвязыванне багацько операцый атрыбутавання ў try/catch. Аўтонамны мікротэст паказаў, што дадатковыя витраты є занедбанымі. Аднак пад час рэальнага атрыбутавання сторынкі обвязыванне кожнага элемента зробіла атрыбутавання прыблізна на 38% дорожэй.
Эта прычына знайома кожнаму, хто рабіць тэсты на JavaScript: у маленькім, павтаральным тэсте оптымаізуючы кампайляр двойчыка можа абэйсці чыста большую частку роботы, якую вы намагаетесь змерыць, таму цячка, яку вы атрымліваеце, відбівае версію вашага коду пасля оптымаізацыі.
Мікротэсты можу падважваць, калі час выканання працоўка оптымізуе самэ тое, што было меравана.
Рашэнне было структурным. Накладныя витраты на выловчэнне бягаў былі обмежаны межамі складовых, а адзінкавыя элементы выкарыстоўвалі дышэўшыяся операцыі зберагання і восстанавлення, каб падтрымаць правільны маршрут. Тэсты типу A/B на рэальных відобразэннях не паказалі ніякых значымых разлікаў. Шырэйшы урок заключаецца ў тым, што працэснасць рендерара залежыць не толькі ад чыстай скорасці, але і ад таго, каб не было падышча ў якосці праз дадаванне функцый, зручных для разработчыкаў, і што кожныя тверджэння пра працэснасць павінны быць перакананы на репрэзентатывных навантажэннях.
Стандартныя настройкі безпекі і порядак абработкі
Базовая прыкладна програма не павінна вымагаць, каб яе разработчык памятаў усі элементы безпекі пры запуску. Stoneware поставляецца з стандартнымі настройкамі, такімі як захопленне ад CSRF і падтрымка Content Security Policy.
Парадакт запуску процесу обработкі каштоўнага запиту є намеровым:
- Спачатку выконуецца захист ад CSRF;
- Пасля таго — працюе мідлвэр аплікацыі;
- Далей выконуецца падбір маршруту та атрыбутаванне дадзеных;
- Усе выходзіць через адны пункт выдачы адпаведзя.
Якщо мідлвэр аплікацыі запускаўся раней, чым выконуецца пераканальчык на CSRF, код корыстніка мог бы потрапіць на маршрут, які амаль ухілваецца ад меры безпекі на рэвэрсе, напрыклад, шляхом ранней выдачы адпаведзя чы перапісву запиту. Закодаванне такога парадакту ў самай рэвэрсе, а не толькі його задокументаванне з надзяёю, што всі яго будуць дазваляць, — гэта саме тая правіла, якуюя рэвэрсе павінна маты. Адны пункт выдачы адпаведзя таксама значыць, што такія заголовкі, як CSP, прыкладзены ўсім адпаведзям аднообразна.
Розшырэнне строгага CSP без яго абяўлення
Рэгламентаваючая палітка ўсталявання яўляецца хорашым стандартам, але рэальныя сайты запускаюць з’явы аналітыки, віджэты для платежаў, API, веб-шрыфты і карты. Частая прычына неяўнакоў — калі разработчык страждае ад блакування якога-небудзь скрыпту і выключае CSP цэлкам. Кращыя падходы дазволяюць расширваць адзінаковыя дырэктывы, захаваючы рештку стандартнай паліткі недзейнаю:
csp: {
scriptSrc: ["https://www.googletagmanager.com"],
connectSrc: ["https://www.google-analytics.com"],
imgSrc: ["https://www.google-analytics.com"],
}
Прынцып заключаецца у безпечных стандартных настройках плюс явным списку дазволеных элементаў для трэціх сторон па кожнай дырэктыве. Пры проектаванні такога API неабходна чыста выявіць, чы рэсурс, які падае, дапамагае стандартной дырэктыве чы заменяе яе, і задокументаваць гэты выбар, адтолькі ўжо таму, што оба варыянты є можлівымі, а іх разлік мае наследкі для безпекі.
Найцяжэйшыя багі застаюцца пасля рэндэра
Фрэймворк не заканчываецца на рэндэрары. Код павінен перазстаць усю дорогу: ад выхіднага коду, праз кампайляр, рэндэрар, процес складання, асеты, праз процедуру развяроўкі, CDN і нарэшце праз браузер. Некалькі з найсложнейшых проблем выявляюцца блізка канцу гэтага ланцоўкі, далека ад коду, які большасць людзей вважае „фрэймворкам“.
Пакаванне асетаў для Vercel
Выпуск 0.1.8 змяніў спосаб развяроўкі Stoneware на Vercel. Для гэтай меты створаныя кліентскія часткі тепер вбудованыя ў серверны пакет як данні у формате base64, што робіць іх частынай пакета, які развяроўкае платформа, і яны выдаюцца з адресы /_stoneware/*.
Stoneware build
↓
server bundle
├── server code
├── CSS assets
└── island assets
↓
Vercel
↓
/_stoneware/*
Гэта функцыя ўвімкнута за выборам і дзейсніца толькі на меты Vercel. Пры розмешчэнні у контейнеры файлы вялікі час ўжо знаходзяцца на дыску, таму немае прычыны трыважваць другую копію кожнага фрагмента ў пакете сервера. Галоўны вывад — платформы для хоставання разлічаюцца тым, што вони включаюць у процес розмешчэння, таму для керавання асетамі часта патрэбны стратегіі, прызначаныя конкретна для кожной меты, а не ўніверсальны раўаненне.
Тэсты, якія падтверджаюць выправленне
У проекте ёсць больш чым 500 автаматызаваных тэстоў, якія перакрываюць рэндерар, маршрутызатор, асэты і сігналы, шаблоны стылю і ўсуненне асэтов, статычны экспорт, механізмы CSRF і CSP, меты розмешчэння, адчуванне памылак, а таксама ворагоўскі чы рэдкісы вхідныя даны, такія як спробы праходжання па шляху, бінарныя файлы і некоректныя шляхі до асэтов.
Сама колькасць не ёсць галоўным пунктам. Болей корыстным стандартам є наступны:
Тэст на регрэсію должен паказаць, што ён бы збыўся да таго, як будзе выкарыстана пасправка.
Тэст, які праходзіць як да змян, так і пасля яных, документуе працэю програмы, але не захоўвае яе ад павтарэння бага. Перакананне, што новы тэст збываецца на старым кодзе, — это простая практыка, якая робіць набор тэстаў значна болей надзеяным.
Існаванне агента для кодавання без аутсорсінгу дизайна
Большая частка проекту Stoneware была реалізавана з викорыстаннем Claude як агента для кодавання. Ён быў особа ўпэўнены ў аналізе расширюючагася кодавага базы, стварэнні повтарюваных элементаў інфраструктуры, напісанні тэстаў, аналізе збоев, рефакторынгу, документаванні архітэктуры і пераглядзе крайніх случаў.
Але ён сам не мог выбраць, якім будзе фрэймворк. Складныя пытанні стосаваліся архітэктуры:
- Для кожнага маршруту, чы ўпэўнены спосаб — SSR чы статычны экспорт?
staticPaths()?Агент можа даследзіць гэтыя пытанні і реалізаваць выбранае рэшэння, але хтось усё рава павінен пераканацца ў правільнасці дизайна і прабавіць рэзультат.
Праўдападобнае — гэта не тое ж сама, што правильнае
Агент для кодавання можа дужа быстро стварыць пераканальную рэалізацыю, і гэта шчына ёй мае вялікую ценнаць. Аднак гэта таксама значыць, што ён можа быстра прабачыцца. Проблема з ресурсамі Vercel ілюструе гэты цыкл. Першая пасправка копіювала створаныя ресурсы ў public/, што здавалася разумным і праходзіла локальныя тэсты; але рэальная разгрузка паказала, што гэта припущэнне было некоректным. Другая спроба змяніла саму модэлю разгрузкі. Тэставанне крайніх сцэнарыяў паказало ўсё новы баг у гэй версіі.
Гэты цыкл — гэта звычная праця над програмнай інфраструктурой, а не адказкі ШІ. Змінюецца толькі швальнасць кожной ітерацыі, чыяму ў рэальным серавысці целі стае яшчэ важлівейшай абоўсюдныя перакананні, а не менш важлівымі.
Чаму выбор часу выканання мае значэнне не толькі для швальнасці
Скарычанне історыі да формулы „Bun ўсё шырэй за Node“ не дастае полнага адчування сутнасці, а чыстая скорасць у будзь-якім разе не ўскладнення філасофіі фрэймворка. Што цікавей, гэта можна перадаць праз стварэнне фрэймворка на асумпцыі, што з самага пачатку є сучасны рантайм і інтеграваны набор з’ёбраў. Комбінацыя Bun – рантайм, калектывны адарожнік, зборка і тэставанне – чыніць яго практычным фундаментам для такога роду архітэктурных експерыментаў.
Дзе паслужае гэтая архітектура
Гэты падход ўсё бол эфективны, калі большая частка стораніцы – це контэнт, а толькі частка з яго є інтерактываючай:
- Дасведчэнні: статыкі і прыклады коду вырабляюцца на сервере; пошук, змінанне тэмы і кнопкі копіювання є аддзельнымі элементамі.
- Е-камерц: дакладныя відомасці продуктаў, атмасферы і контэнт для SEO таксама вырабляюцца на сервере; корзіна і фільтры є аддзельнымі элементамі.
Дзе гэты інструмент, верагодна, не падходзіць
Якщо ваш прылад фактычна ёсць дэсктопным праграмам, якая працуе ў браузеры — напрыклад, саавтарскі редактор, інструмент для графікі, гэм, інтэрактыўная панель керування або будзь-які прылад, дзе практычна кожны компонент працуе на кліянтавай стороне, то частка старонкі, якая можа застацца у формате HTML, є мала. У такім случыку модэль з аддзельнымі элементамі стварае межы без значнага зменшэння працы, і архітектура, оріѐнтаваная на кліянта, верагодна будзе болей падходячая. Фрэймворк можа маты чыстае мненне, не прэтвараючыся, што ён падходзіць для кожных заведамосцей.
Пробаўка
У момент напісання глазурованая кераміка яшчэ знаходзіцца ў версійнай серыі 0.1.x, таму можна спакавацца з недосконаласцямі, а таксама пераканацца ў потычным статусе у репазітарыі. Серед запланаваных паўрабоцоў — большая колькасць інтеграцый, павышанная діагностика та апавяшэння пра проблемы пад час разработкі, больш прыкладоў та цэлей для развяртання, адносна более дакладная документацыя та больш рэальных прыкладаў выкарыстання. Чым стварыць каркас проекту та запусціць сервер разработкі:
bun create stoneware my-app
cd my-app
bun dev
Хорашым першым эксперыментам є ўсё тое, што мае невялікі розмер, але большую колькасць контэнту: блог, сайт дакументацыі, каталаг продуктаў, портфолій чы бізнес-сайт. Падчас стварэння такога проекту постаўляйце сабе пытанне, насколькі самэў дакумента ў реальнасці патрабуе JavaScript.
Ключовыя выводы
- Вважайце HTML стандартным выходам і робіце викорыстанне JavaScript на боку кліента опцыйным для кожнага компонента; таким чынам стораніца будзе мятаць скрытую програмную частку, а не быць цэлым прыкладам прыемлівання.