Repository navigation
Releases
Releases · yartema/tusten-framework
v0.2.0-beta.7
Added
- Каталог навигации из дерева маршрутов. Поле
route.navigation(opt-in) помечает маршрут пунктом меню;getNavigation()возвращает плоский каталог (id,href,parentId,dynamic,slug+ прикладные ключи),buildNavigation(routes)— то же без состояния (тесты,sitemap.xml).hrefдля статического маршрута берётся из пути, явныйnavigation.hrefпобеждает, динамический маршрут без явногоhrefотдаётся сdynamic: trueбез ссылки. Ключи (title,icon,order, права) — приложение через module augmentationTustenRouteNavigation; значения проверяются на JSON-safety вbuildRouteTree. Каталог статичен, засеивается вglobalThisв client-entry иcreate-server, в__ROOT_STATE_STR__не попадает.getNavigation()импортируется из client-safe@tusten/core, поэтому работает и на клиенте, и в кастомном JSON-RPC-обработчике: сервер может вернуть каталог (при необходимости отфильтрованный по правам/ctx) клиенту обычнымService.call. - Сжатие HTTP-ответов включено по умолчанию (brotli + gzip).
@fastify/compressсжимаетPOST /service, API-роуты и статику; SSR-документ и готовые HTML-тела (SPA-shell, 404, страницы ошибок) сжимаются встроенным zlib-пайплайном, потому что SSR пишет вreply.rawв обход хуков Fastify. Кодировка выбирается поAccept-Encoding,Vary: Accept-Encodingмёржится с i18n-значением. Новый конфигserver.compress?: false | { threshold?, encodings?, ssr? };falseполностью выключает сжатие (когда сжимает прокси/CDN),ssr: false— только стримируемый HTML. publicDir— каталог статики рядом сclient/иserver/(по умолчаниюpublic,false— отключить). Vite обслуживает его в dev и копирует вdist/clientна сборке; prod-сервер дополнительно читает исходный каталог через@fastify/static(артефакты сборки имеют приоритет). Хэшированные чанки/ассеты (включая entry) получаютCache-Control: public, max-age=31536000, immutable, файлы изpublic/—no-cache.- Хэшированные имена ассетов и
immutable. Entry-чанк клиента, чанки и CSS получают хэш в имени (assets/client-entry-<hash>.js,assets/<name>-<hash>.js,assets/<name>-<hash>.css) и отдаются сCache-Control: public, max-age=31536000, immutable. URL entry для<script type="module">берётся из Vite manifest (findClientEntryFile), поэтому деплой не требует правок в шаблоне; файлы изpublic/по-прежнемуno-cache. - Предсжатие статики (Brotli + Gzip).
buildClientпосле записи бандла создаёт рядом с текстовыми файлами (js,css,html,json,svg,xml,txt,map— крупнее 1 КБ).br(brotli quality 11) и.gz(gzip level 9). Prod-сервер включает@fastify/static.preCompressed: true: отдача поAccept-Encodingбез CPU на каждый запрос, с автоматическимVary: Accept-Encodingи откатом на несжатый файл. Утилита —precompressAssets(dir, options)вbuild/precompress.ts. startTransitionпри SPA-переходе и публичныйpending. Новое дерево рендерится в transition: старая страница остаётся на месте, пока грузятся данные и чанки.useNavigation()получилpending, добавленыuseNavigationPending(),isNavigationPending(),subscribeNavigationPending(),setNavigationPending()и готовая полоска<NavigationProgress />(рендерится в root controller, при SSR невидима, клики не перехватывает).create-tusten-app— скаффолдер новых приложений (npm create tusten-app@latest my-app). Один шаблонbasic, вопросы про Tailwind / ESLint / Prettier, выбор пакетного менеджера (pnpm по умолчанию), установка зависимостей иgit initпо желанию. Версии@tusten/coreи его peer-зависимостей берутся изpackages/tusten/package.jsonпри сборке скаффолдера. В шаблоне JSON-RPC включён по умолчанию: объектApp(server/app/App.meta.ts), клиентский вызов черезService(client/Page/Factories/appInfo.ts) и SSR-prefetch данных, плюсpublic/и сжатие ответов. Публикация пока не выполнялась.- Алиасы из
tsconfig.jsonработают и на сервере. Загрузчики на jiti (tusten.config.ts,router.ts,*.loader.ts, server routes/plugins/middleware, RPC-объекты,configLoaderмаршрутов) читаютcompilerOptions.pathsчерезcreateProjectJiti, поэтому@/…и@server/…резолвятся одинаково в редакторе,tsc, Vite и Node. В Vite пути включаются опциейvite.resolve.tsconfigPaths; скаффолдер создаётpathsдляclient/иserver/.
Breaking
SliceRegistry.adoptPage()/adoptGlobal()больше не уничтожают вытесненные слайсы сразу. Они возвращают идемпотентнуюrelease()-функцию: client-entry вызывает её после commit нового дерева (startTransition), иначе старая страница осталась бы смонтированной с уничтоженными слайсами. Прямые вызовы, которые игнорировали возвращаемое значение, должны вызыватьrelease()самостоятельно — иначе слайсы утекут доdispose*.@tusten/core/clientбольше не реэкспортирует core API. Убранexport * from '..': клиентский entry содержит только React API и клиентский рантайм (RootProvider, хуки,Link,Outlet,Remote,RootErrorBoundary/RootLoading/RootNotFound, i18n,devalueParse/devalueStringify).defineConfig,defineRoute,defineGlobalLoader,Slice,AbstractSlice,SliceRegistry,Service,TustenError,RpcError,runGlobalPrefetch/runPagePrefetch/runPrefetch,computePath,resolveMeta,toClientRoute/pickClientRoute/collectParentIdsи общие типы импортируются из@tusten/core.- Из
@tusten/core/serverубраны дубли core-экспортов.TustenError,RpcError,runPrefetch,runGlobalPrefetch,runPagePrefetchи типы prefetch остаются только в@tusten/core;server/prefetch.tsудалён. Серверный entry — только Node-only API. - RPC-типы — только в
@tusten/core/server.RpcContext,RpcOptions,ResolvedRpcOptions,RpcObjectDefinition,RpcMethodDefinition,RpcParamsSchema,AuthRequirement,RpcExecutor,StandardSchemaV1больше не экспортируются из@tusten/core. registerServerPlugins(fastify, plugins, projectDir)— третий аргумент обязателен: без корня проекта jiti не находитtsconfig.jsonи не применяетpaths.
Changed
- Пользовательская документация по данным.
docs/Factories.md— фабрики, аргументы, зависимости,Service, SSR/SPA-пайплайн;docs/Slices.md— слайсы,setState, хуки, жизненный цикл, сериализация иSliceRegistry. Ссылки добавлены вREADME.mdиdocs/Router.md. - Пользовательская документация по конфигурации.
docs/Config.md—defineConfig, все секцииtusten.config.ts, значения по умолчанию, пути, рецепты и ограничения. Ссылка добавлена в раздел «Конфиг» корневогоREADME.md. dist/serverбольше не содержит копиюpublic/. SSR-сборка запускается сpublicDir: false: статика копируется один раз вdist/client, а SSR-бандл не раздувается.defineRoute: обязательны толькоidиcontentConfig.workspaceConfig.template.prefetchConfigстал опциональным: без него у страницы нет page-слайсов,configLoaderне грузится ни на сервере, ни на клиенте, а в__ROOT_STATE_STR__едут только глобальные слайсы. Глобальные слайсы и*.loader.tsтоже необязательны: проект с одной страницей без единого загрузчика собирается и рендерится,globalRegistryпустой. ЗатронутыrunPagePrefetch, манифест, Vite-плагин и сбор фабрик.
Fixed
- Конфиг без
export defaultбольше не игнорируется молча.jitiсinteropDefaultна модуле без экспортов возвращает{ default: {} }, иloadConfigпринимал пустой объект за валидный конфиг: сервер стартовал на дефолтах, пропадалиclient.css,client.root, i18n и Vite-плагины (например, Tailwind не подключался). Теперь —TustenError: Config at … must export a default object. - Source maps теперь попадают в npm-пакет.
dist/**/*.mapисключались изfiles, хотя сборка (tsupсsourcemap: true) оставляет в JS комментарии//# sourceMappingURL=…. Vite у потребителя пытался прочитать отсутствующий файл и писал при каждом стартеFailed to load source map … ENOENT. Карты self-contained (sourcesContent), поэтому стеки SSR снова маппятся в исходные.ts/.tsx.
v0.2.0-beta.6
Breaking
- Дефолтное имя cookie с выбранным языком —
lang(былоtusten_locale). Старые cookie больше не читаются: пользователь один раз получит язык изAccept-Language/defaultLocale. Вернуть прежнее имя —defineConfig({ i18n: { key: 'tusten_locale', defaultLocale, locales } }). client.layoutsиroute.typeудалены. Layout теперь задаётся вdefineRouteчерезroute.layout:'Page/Layout:Main', массив для вложенности илиfalse/[]для отказа. Если в конфиге естьclient.layouts, загрузчик выведет warning и проигнорирует его. Если в маршруте осталсяtype,buildRouteTreeтоже выведет warning.client.rootElementудалён и заменён наclient.root.container.client.rootтеперь объект{ component?, container? }; короткая строкаroot: 'Page/Controller:Root'поддерживается только дляcomponent.
Added
slice.state— прямое чтение состояния слайса как свойства (slice.state).getState()оставлен@deprecated-алиасом и больше не используется внутри фреймворка, в примерах и документации.- Root controller (
client.root.component) — компонент-оболочка всего приложения, которая рендерится всегда: SSR, гидрация, SPA-loading, ошибка и 404. Получаетchildren,route,router,status(ready/loading/error/not-found) иerror. Внутри доступныuseSlice/useRouter/useRoute, а React-контекст корня видят все layouts и страницы. Не задан — поведение как раньше, без обёртки. useRoute()— публичный конфиг текущего маршрута в root controller, layouts и страницах. Новый типTustenClientRoute— JSON-safe проекцияTustenRoute; на сервере и клиенте используется одна функция проекции, поэтому нет hydration mismatch.route.layout— layout как часть маршрута: строка (полная цепочка), массив (явная вложенность root → leaf),undefined(наследовать отparentId),false/[](без layout'ов). Строка/массив заменяют унаследованную цепочку, дубликаты подряд удаляются. Layout всегда опционален.client.root.container— настройка контейнера приложения:tag(по умолчаниюdiv),id(по умолчаниюroot,false— без id) иattributes(class,data-*,aria-*,style, ...). Клиент находит контейнер по служебномуdata-tusten-root, поэтому смена id/тега не ломает гидрацию. Событийные атрибуты (on*) запрещены — это статичный HTML.i18n.key— имя cookie с выбранным языком. Действует и на сервере (resolveRequestLocale), и на клиенте (setLocale); ключ уезжает вwindow.__ROOT_I18N__(cookieKey), поэтому SSR и гидрация используют одно и то же имя. Дефолт —LOCALE_COOKIE(lang). Имя валидируется при загрузке конфига (RFC 6265 token, обрезается по краям): пустая строка, пробелы и разделители —TustenError.<html lang>— SSR, SPA и 404 отдают атрибутlangс locale запроса (нужен скринридерам, SEO, спеллчекеру и CSS:lang()). При выключенном i18n атрибут не рендерится.RootErrorBoundaryполучилresetKey: при SPA-навигации пойманная ошибка больше не «залипает» после перехода на другую страницу.- Тесты на кастомный ключ cookie:
config,negotiate,boot,locale,runtime,ssr-head. Всего 497 тестов (32 файла). - Dev-оверлей ошибок в браузере. Падение SSR отдаёт отдельную страницу с описанием, стеком и code frame вокруг строки; стек маппится по sourcemap через
vite.ssrFixStacktrace(в кадрах исходные.tsx), кадры кликабельны и открывают файл в редакторе (/__open-in-editor). - Ошибки SSR после отправки shell (стриминг) уезжают в HTML как
window.__TUSTEN_SSR_ERRORS__; клиент показывает их оверлеем поверх частичной страницы, потому что статус ответа уже отправлен. - Клиентский оверлей (
@tusten/core/client/dev-overlay, shadow DOM): описание, стек, копирование, переход в редактор, закрытие по Esc. Ловит гидрацию (onRecoverableError), SPA-навигацию, initial prefetch,window.error/unhandledrejectionи ошибки, пойманныеRootErrorBoundary. Одинаковые ошибки дедуплицируются; при сбое динамического импорта оверлей подсказывает проверить, запущен ли dev-сервер. - Prod-страница 500 с коротким
Код ошибкии без стека/путей; код пишется в лог ([tusten] <label> [id]: …) и связывает ответ пользователя с записью. - Новая точка входа пакета
@tusten/core/client/dev-overlay(tsup entry +exports); в prod-бандл не попадает — entry импортирует её динамически внутриif (import.meta.env.DEV). useNavigation()— единый хук навигации:pathname,params,query,routeи методыpush/replace/back/prefetch/reload. Заменяет связкуuseRouter()+usePathname()+useParams()+useQuery().router.reload(options?)— перезапуск лоадеров текущего маршрута без смены URL и history. По умолчанию обновляет глобальные и page-слайсы, сбрасывает клиентский кэшServiceи сохраняет локальный state компонентов. Опции:global(по умолчаниюtrue),cache(false— сбросить кэш),remount(перемонтировать страницу),middleware(прогнать клиентскую цепочку). Ошибка не заменяет страницу наcomponents.error; при гонке с навигацией побеждает последняя операция. До инициализации client-entry — полная перезагрузка.SliceRegistry.adoptGlobal(source)— атомарная подмена global-слайсов (используетсяrouter.reload, чтобы при ошибке не оставить частично обновлённые глобальные состояния).
Deprecated
useRouter(),usePathname(),useParams(),useQuery()— используйтеuseNavigation(). Старые хуки остаются тонкими обёртками.
Fixed
- После
router.reload()переставали обновляться слайсы.adoptPage/adoptGlobalзаменяют инстансы безnotifyKey, аuseSliceоставался подписан на уничтоженный слайс:setStateнового инстанса не вызывал re-render. ТеперьsubscribeдляuseSyncExternalStoreзависит от текущего инстанса и переподписывается после подмены. - SSR игнорировал cookie с locale. В
readLocaleCookieусловиеpair.slice(0, idx).trim() !== key || LOCALE_COOKIEбыло всегда истинным, поэтому выбор пользователя (setLocale) не учитывался — locale всегда бралась изAccept-Language/defaultLocale. - SPA-навигация при ошибке больше не молчит. Если
clientPrefetchили загрузка чанка маршрута падают, рендеритсяcomponents.error(в dev плюс оверлей), а не остаётся старая страница без объяснения. - Back в SPA терял query-параметры. Обработчик
popstateпередавал толькоwindow.location.pathname, поэтому back с/about?tab=routerвёл на/about, аreplaceStateзатирал предыдущие записи истории. Теперь учитываетсяpathname + search, и back возвращает на предыдущую вкладку/страницу. - Фатальный сбой клиента в SPA (без SSR) показывает текст «Не удалось загрузить страницу. Обновите её» вместо пустого экрана; SSR-разметка при этом не затирается.
- В dev- и prod-ответах 500 используется один и тот же путь
fail(): раньше dev отдавал<pre>с однимmessage, без стека и без code frame.
Changed
- Пути в
client.*задаются относительноclientDirбез./:Page/Controller:Root,layouts/Main. Старый вид с./поддерживается — нормализуется при загрузке конфига. window.__ROOT_I18N__содержитcookieKey;I18nBootstrap.cookieKeyприменяется вinitI18nчерезsetLocaleCookieKey.- CHANGELOG переехал в
packages/tusten/CHANGELOG.mdи отслеживается git;prepackбольше не копирует его из корня. - README: цепочка определения locale и пример конфига описывают
i18n.keyи дефолтlang.
v0.2.0-beta.5
Breaking
- Формат
tusten.config.tsприведён к структуреResolvedTustenConfig:export default defineConfig({ ssr: true, client: { clientDir: 'client', layouts: { main: './layouts/Main.tsx' }, css: ['styles/main.css'], components: { error, loading, notFound }, }, server: { serverDir: 'server', port, host, routes, plugins, rpc }, middleware, vite, build, runtimeConfig, fastify, })
clientDir,layouts,css,componentsпереехали вclient;serverDirиrpcпереехали вserver;cssтеперь массив путей (было{ main: string }) — в dev каждый файл даёт свой<link>.
Slice.dispose()→Slice.destroy().dispose()оставлен как@deprecated-алиас, но теперь тоже очищает state. Уничтоженный слайс:setState— no-op (+console.warnвне production),subscribe— пустая отписка.SerializedState.slices[*].config— новый элемент__ROOT_STATE_STR__(в типеoptionalдля чтения старых снимков).
Added
AbstractSlice.destroy()/isDestroyed(); уничтожение освобождает подписчиков и state._initState(result, config)/hydrate(result, config): вторым аргументом приходитdataFactoryArgumentsфабрики. Config сериализуется в__ROOT_STATE_STR__, поэтому SSR-гидратация на клиенте получает те же значения, что и сервер.SliceRegistry.adoptPage(source)— атомарная подмена page-слайсов при SPA-навигации;setPage/setGlobalуничтожают заменяемый инстанс.setStateдля plain-объектов делает поверхностный мерж (было — полная замена):setState({ total: 0 })сохраняет остальные ключи. Для массивов,Map/Dateи экземпляров классов — замена. Новый публичный типSlicePatch<TState>.- SSR: заголовки
Cache-Control: no-storeиVary: Accept(404), кэшloadModuleв prod, статические фрагменты документа вынесены из per-request пути. utils/fs:resolveRealPath()иtoVitePath()— канонический регистр путей для Vite/HMR.getRouter()— навигатор без React-контекста для обработчиков, сервисов и таймеров. Тот же API, что уuseRouter().- i18n клиентских модулей. Импорт
import rk from 'i18n!<Module>'(единственный синтаксис). Словари —client/<Module>/lang/<locale>/<locale>.json; конфиг —defineConfig({ i18n: { defaultLocale, locales } }).rk(key, ctx?)— ключ = текст на исходном языке, поискctx@@key→key; нет перевода → ключ, без ошибок. Битый JSON и нестроковые значения — ошибка сборки.template(str, params, locale?)—{name}и{n, plural, one {…} few {…} many {…} other {…}}(подмножество ICU,otherобязателен).- Locale: cookie
tusten_locale→Accept-Language(сq) →defaultLocale. SSR-рендер и словари встраиваются в HTML; гидрация без mismatch. Параллельные запросы изолированы черезAsyncLocalStorage. setLocale(l)(@tusten/core/client) — cookie и перезагрузка страницы. Реактивного переключения нет.- Типы:
declare module 'i18n!*'подключается через@tusten/core/client. - Тесты:
i18nTestPlugin()из@tusten/core/server— в Vitesti18n!Xпревращается в заглушку,rk(key)возвращаетkey. tusten inspectпечатает i18n-модули: число ключей по locale, отсутствующие словари, ошибки JSON.
Fixed
- HMR на Windows/macOS: правка компонента не подхватывалась без перезапуска dev, если регистр в спеке не совпадал с файлом (
'HomePage/view'↔View.tsx). Причина — Vite регистрировал модуль подview.tsx, а watcher присылалView.tsx. Пути канонизируются черезrealpathSync.nativeвmodule-loader,vite/pluginиserialize. serialize:modulePathломался, когдаprojectDirбыл коротким путём (C:\Users\AV-BAR~1\...), аrealpath— длинным (../../../../../...).- SSR: исключение после
reply.hijack()(парсинг URL, 404-рендер, middleware) оставляло запрос висеть до таймаута — добавлен внешнийtry/catchи guard на повторныйend(). В production клиенту больше не уходит текст внутренней ошибки. queryToObjectпадал сURIErrorна битом percent-encoding (?a=%) — заменён наURLSearchParams.- SPA-переход: при ошибке
loadDataновая страница больше не оставляет пользователя с уже уничтоженными слайсами — prefetch идёт в отдельный реестр, подмена только после успеха. - независимые фабрики грузятся параллельно, и для
runPagePrefetch, и дляrunGlobalPrefetch. Каждая ждёт только свои зависимости. Порядок записи вslicesиregistryостался прежним (топологический) - чанки шаблона и
layout,Errorи классы слайсов грузятся параллельно.LoadingвSSRбольше не качается. Добавил защиту от устаревшей навигации,onRecoverableErrorдляhydrationmismatchи прогрев чанка шаблона при prefetch. resolveMeta больше не блокируетSPA-переход, иdocument.titleперестал затираться (раньшеroute.titleперетирал заголовок изmeta). CSSберётся по всей цепочкеlayoutи из imports. В<head>добавленmodulepreloadдляclient.js, чанков маршрута и слайсов. Слои и шаблон грузятся параллельно,ErrorComponentстартует доprefetch.
Changed
examples/basicпереведён на новую структуру конфига;UserListState.limitдемонстрирует второй аргумент_initState.- Документация:
packages/tusten/README.md— генерируемая копия корневого (prepack), правило зафиксировано вAGENTS.md; файл добавлен в.gitignore. useRouter()— тонкая обёртка надgetRouter(). Вызов вне<RootProvider>больше не бросаетTustenError.
v0.2.0-beta.4
- MetaResult: optional 'title' field
- resolveMeta: title priority = fromMethod > metaConfig.title > 'Страница'
- Service: LRU cache (cacheMaxEntries, default 500)
- Service: cacheSize() for tests
- Service/RpcError exported as-is (no Tusten prefix)
- Published: @tusten/core@0.2.0-beta.4"
v0.2.0-beta.1
- Scoped package @tusten/core
- Bin 'tusten', imports '@tusten/core'
- RootProvider / TustenError / RpcError / defineConfig / createServer
- 264 tests, CI green
- Published: beta + latest tags on 0.2.0-beta.1"
v0.2.0-alpha.3
refactor!: rename nixo -> setti