@tusten/core
v0.2.0-beta.7
Published
Fullstack React framework on React 19 + Fastify + Vite
Maintainers
Readme
Tusten Framework
Fullstack React framework on React 19 + Fastify 5 + Vite.
tusten — мета-фреймворк уровня Nuxt/Next, который собирается из трёх проверенных инструментов: React, Fastify, Vite. Устанавливается как зависимость, сканирует client/, строит карту маршрутов, поднимает сервер с SSR/SPA и JSON-RPC 2.0 — без магии, без RSC, без Server Actions.
⚠️ Beta (
@tusten/[email protected]).
- Новый проект:
npm create tusten-app@latest my-app(илиpnpm create tusten-app my-app)- Установка в существующий проект:
pnpm add @tusten/core@beta- Импорт:
import { defineConfig } from '@tusten/core'- Bin:
tusten dev,tusten build,tusten start,tusten inspect- API стабилизируется, breaking changes — только в минорных версиях.
- Не для production без тестов и ревью.
- Что нового в beta.7 —
create-tusten-app, каталог навигации (getNavigation), сжатие ответов и предсжатие статики,publicDir, хэшированные ассеты,startTransition+pending, алиасы изtsconfig.jsonи необязательныйprefetchConfig:packages/tusten/CHANGELOG.md.- Следите за Releases.
✨ Что внутри
- SSR из коробки —
renderToPipeableStream+hydrateRoot, стриминг, единый React Context между сервером и клиентом. - SPA по требованию — глобально (
ssr: false), per-route (route.ssr: false) или через?noSSR=trueдля отладки. - Файловый роутинг —
client/*/router.ts→defineRoute([...]). Динамические сегменты черезslug: ['/regex:[a-z0-9-]+']илиpath: '/blog/:slug'. - Вложенные layouts —
route.layout(строка/массив), наследование поparentId, замена/сброс цепочки; layout всегда опционален.<Outlet/>илиprops.childrenна выбор. - Root controller —
client.root: одна оболочка приложения на все страницы и состояния (SSR, loading, error, 404) с route/router/status и своим React-контекстом. - SEO / meta —
metaConfigна маршруте: статика (title,meta[],microdata) + динамика черезreadMethod(JSON-RPC) илиgetMetaCallback. ПлюсusePageMetaдля компонента. JSON-LD из коробки. - i18n клиентских модулей —
import rk from 'i18n!HomePage', словариclient/<Module>/lang/<locale>/<locale>.json,template()с ICU-plural,setLocale()через cookie. SSR встраивает переводы в HTML — гидрация без mismatch. - JSON-RPC 2.0 из коробки —
defineObjectвserver/**/*.meta.ts, endpoint/service, batch, валидация через Standard Schema (valibot / zod / arktype), auth,ctx.call,System.Describe. - Три реестра middleware — client-page, server-page, server-api. Не смешиваются, наследуются по
parentId. - Слайсы — собственный реактивный store (
Slice/AbstractSlice/SliceRegistry). Page-scoped и global,destroy()/isDestroyed()при навигации,_initState(result, config)с сериализациейconfigв SSR-state, мержsetStateдля plain-объектов, атомарная подмена страницы черезadoptPage(),useSlice/useStrictSlice/useSliceRef. - Навигация — единый хук
useNavigation()(pathname/params/query/route+push/replace/back/prefetch/reload);getRouter()доступен обработчикам, сервисам и таймерам вне React. - Cross-page кэш в
Service— TTL,invalidate(), LRU-эвикция (cacheMaxEntries, default 500),<Link prefetch>заполняет кэш по hover. Не на уровне страниц — на уровне вызовов. devalueдля сериализации —Map,Set,Date,BigInt,undefined,NaN, циклы переживают SSR и восстанавливаются на клиенте.- Client-safe разделение — три runtime-точки входа:
@tusten/core(pure TS),@tusten/core/server(Node-only),@tusten/core/client(React), плюс types-only@tusten/core/i18nдляi18n!*.@tusten/coreне тянет jiti/fastify/vite. - Error boundaries / Loading / Not Found — через
client.components, с дефолтамиRootErrorBoundary/RootLoading/RootNotFound. - Prod build —
tusten build→dist/client+dist/server.tusten start— Fastify + статика. - 663 unit-теста (Vitest, 49 файлов,
tests/tusten) — ядро покрыто на 90%+, CI на GitHub Actions.
🚀 Быстрый старт
Из шаблона
pnpm create tusten-app my-app
cd my-app
pnpm devШаблон уже включает SSR, включённый JSON-RPC (server/app/App.meta.ts + вызов через Service в client/Page/Factories/appInfo.ts), статику public/ и сжатие ответов.
Из npm
mkdir my-app && cd my-app
pnpm init -y
pnpm add @tusten/core@beta react react-dom fastify vite @vitejs/plugin-react
pnpm add -D typescript @types/react @types/react-domСоздайте tusten.config.ts:
import { defineConfig } from '@tusten/core'
export default defineConfig({
ssr: true,
client: {
css: ['styles/main.css'],
},
})Создайте client/HomePage/router.ts, client/HomePage/view.tsx, client/layouts/Main.tsx (примеры ниже) и запустите:
pnpm exec tusten dev
# → http://127.0.0.1:3000Из монорепо (для разработки)
git clone https://github.com/yartema/tusten-framework.git
cd tusten-framework
pnpm install
pnpm dev:basicОткройте http://127.0.0.1:3000 — демо на Tailwind v4 с 4 страницами (Home / About / Blog / Admin), API, JSON-RPC, meta, i18n (ru/en) и вложенными layouts. На Windows используйте 127.0.0.1, а не localhost (последний может резолвиться в ::1).
Другие команды:
pnpm lint # ESLint
pnpm typecheck # tsc --noEmit
pnpm test # Vitest (663 теста, 49 файлов)
pnpm inspect:basic # dump маршрутов, RPC-методов и i18n-словарей
pnpm build:basic # prod-сборка
pnpm start:basic # prod-сервер🧑💻 Как это выглядит
Маршрут
// client/HomePage/router.ts
import { defineRoute } from '@tusten/core'
export default defineRoute([
{
id: 'home',
index: true, // URL: /
layout: 'layouts/Main', // путь до layout'а; можно не задавать
middleware: [{ id: 'auth', handler: 'client/middleware/auth' }],
metaConfig: {
title: 'Главная',
meta: [{ name: 'description', content: 'Home page' }],
},
contentConfig: {
// обязателен только template
workspaceConfig: { template: 'HomePage/view:View' },
// необязательно: без prefetchConfig у страницы нет page-слайсов
prefetchConfig: {
configLoader: 'HomePage/Factories/Root',
dependencies: ['userInfo'], // глобальный loader
},
},
},
])Обязательные поля маршрута — только id и contentConfig.workspaceConfig.template.
layout, index, metaConfig, middleware, path / slug, ssr, meta и
contentConfig.prefetchConfig можно не задавать. Глобальные слайсы
(*.loader.ts) тоже опциональны: страница без загрузчиков собирается и
рендерится, globalRegistry при этом пустой.
Динамический маршрут с meta из RPC:
// client/BlogPage/router.ts
export default defineRoute([
{
id: 'blog',
slug: ['/regex:[a-z0-9-]+'],
layout: 'layouts/Main',
metaConfig: {
readMethod: 'Blogs.ReadMetaInfo', // вернёт { title, meta[], microdata }
cache: 60_000,
meta: [
// статика мержится: [...static, ...fromMethod]
{ name: 'og:type', content: 'article', attribute: 'property' },
],
},
contentConfig: {/* ... */},
},
])SEO / meta
Три уровня (по убыванию приоритета):
readMethod— путь до JSON-RPC метода ('Blogs.ReadMetaInfo'). Вызывается с полным URL. Возвращает{ title?, meta?: MetaTag[], microdata?: object }.getMetaCallback— путь до функции(metaConfig) => Promise<MetaResult>. Вызывается, еслиreadMethodне задан.- Статика в
metaConfig:title,meta: MetaTag[],microdata.
Мерж статики и метода:
meta— конкатенация:[...static, ...fromMethod](статика первая).microdata— shallow merge:{ ...static, ...fromMethod }.title— приоритет:fromMethod.title>metaConfig.title>'Страница'.
MetaTag = { name: string; content: string; attribute?: 'name' | 'property' } — для OG/Twitter указывайте attribute: 'property'.
Серверный handler readMethod:
// server/blogs/Blogs.meta.ts
import { defineObject } from '@tusten/core/server'
import * as v from 'valibot'
export default defineObject({
name: 'Blogs',
description: 'Блог',
methods: {
ReadMetaInfo: {
description: 'Возвращает meta для поста',
params: v.string(), // url
handler: async (url) => {
const slug = new URL(url).pathname.split('/').pop() ?? 'unknown'
return {
title: `Post ${slug} — Blog`,
meta: [
{ name: 'description', content: `Post ${slug}` },
{ name: 'og:title', content: `Post ${slug}`, attribute: 'property' as const },
],
microdata: {
'@context': 'https://schema.org',
'@type': 'BlogPosting',
headline: `Post ${slug}`,
},
}
},
},
},
})Клиентский usePageMeta (client-only, для динамики внутри компонента):
import { usePageMeta } from '@tusten/core/client'
export function View() {
usePageMeta({
title: 'Custom title',
meta: [{ name: 'description', content: '...' }],
microdata: { '@type': 'Article' },
})
return <div>...</div>
}SSR — no-op (meta из metaConfig уже в <head>).
Prefetch фабрик
// client/HomePage/Factories/Root.ts
import type { FactoryMap, TustenRouter } from '@tusten/core'
export default function getConfig(configParams: Record<string, unknown>, router: TustenRouter): FactoryMap {
return {
UserList: {
dataFactoryName: 'HomePage/Factories/usersList:UserListLoader',
dataFactoryArguments: { limit: 10 },
dependencies: [],
},
}
}Слайс + изоморфный loadData
// client/HomePage/Factories/usersList.ts
import { Slice, Service, type FactoryImplementation } from '@tusten/core'
interface User {
id: number
name: string
}
interface UserListState {
users: User[]
total: number
limit: number
reload: () => void
}
const usersService = new Service({
endpoint: 'Users',
binding: { query: 'List' },
cache: 30_000, // TTL
cacheMaxEntries: 500, // LRU limit (default 500)
})
export class UserListSlice extends Slice<UserListState> {
protected override _initState(result: unknown, config?: unknown): UserListState {
const { users } = result as { users: User[] }
// `config` — это `dataFactoryArguments` фабрики (`getConfig`).
// Он сериализуется в __ROOT_STATE_STR__, поэтому при SSR-гидратации
// `_initState` получит те же значения, что и на сервере.
const { limit = 10 } = (config ?? {}) as { limit?: number }
return {
users,
total: users.length,
limit,
reload: () => {
/* создаётся заново и на сервере, и на клиенте */
},
}
}
}
// `slice.setState({ total: 0 })` для plain-объектов мержит патч в текущий state:
// переданные ключи заменяются, остальные (`users`, `reload`) сохраняются.
// Для массивов, `Map`/`Date` и экземпляров классов `setState` заменяет значение.
// Если переопределяете `destroy()`, обязательно вызывайте `super.destroy()`.
export const UserListLoader: FactoryImplementation<UserListState> = {
async loadData(args) {
const limit = (args.limit as number) ?? 10
const users = await usersService.query<{ limit: number }, User[]>({ limit })
return { users }
},
slice: UserListSlice,
// Необязательно: динамические args поверх `dataFactoryArguments`, изоморфно.
// getDataFactoryArguments: async () => ({ limit: 20 }),
}Подробные руководства: docs/Factories.md — фабрики,
аргументы, зависимости и ошибки; docs/Slices.md — слайсы,
setState, хуки, жизненный цикл и сериализация.
Компонент
// client/HomePage/view.tsx
import { useSlice, useNavigation, Link } from '@tusten/core/client'
import type { UserListSlice } from './Factories/usersList'
export function View() {
const slice = useSlice<UserListSlice>('UserList')
const state = slice?.state
const nav = useNavigation()
if (!state) return <div>Loading…</div>
return (
<div>
<h1>HomePage ({nav.pathname})</h1>
<p>Users: {state.total}</p>
<Link href="/about" prefetch>
→ About (SPA, prefetch on hover)
</Link>
</div>
)
}Обновление данных (SPA)
Все навигационные возможности собраны в одном хуке — useNavigation():
const nav = useNavigation()
nav.pathname // текущий путь
nav.params // динамические сегменты
nav.query // query-параметры
nav.route // конфиг маршрута (TustenClientRoute | null)
nav.pending // true, пока идёт переход (middleware + prefetch + commit)
await nav.push('/about')
await nav.replace('/about')
await nav.reload()nav.reload() перезапускает лоадеры текущего маршрута, не перезагружая
браузер: URL и history не меняются, root controller и layouts остаются
смонтированными.
await nav.reload() // все лоадеры + свежие данные
await nav.reload({ global: false }) // только page-лоадеры
await nav.reload({ remount: true }) // перемонтировать страницуuseRouter(), usePathname(), useParams() и useQuery() остались как
deprecated-обёртки; getRouter() — для кода вне React.
Подробное руководство по навигации, <Link>, prefetch и reload —
docs/Router.md.
| Опция | По умолчанию | Что делает |
| ------------ | ------------ | ---------------------------------------------------------------------- |
| global | true | Перезапускает глобальные loader'ы (defineGlobalLoader) |
| cache | false | false — сбрасывает клиентский кэш Service; true — разрешает кэш |
| remount | false | true — новый key у шаблона страницы (локальный state сбрасывается) |
| middleware | true | Прогоняет клиентскую middleware-цепочку |
Ошибка reload не заменяет страницу на components.error: пользователь
остаётся на текущей странице, ошибка уходит в dev-оверлей/лог, а Promise
реджектится. Если во время reload началась навигация — побеждает последняя
операция. До инициализации client-entry reload() делает полную перезагрузку.
Индикатор загрузки
Новый экран рендерится в startTransition: пока грузятся данные и чанки,
пользователь остаётся на старой странице, а фреймворк сообщает о переходе через
useNavigation().pending или useNavigationPending(). Слайсы старой страницы
уничтожаются только после commit нового дерева — до этого момента она полностью
рабочая.
Готовая полоска сверху — <NavigationProgress />. Рендерится в root controller,
при SSR отдаётся невидимой (hydration не расходится), не перехватывает клики:
import { NavigationProgress, type RootControllerProps } from '@tusten/core/client'
export function Root({ children }: RootControllerProps) {
return (
<div>
<NavigationProgress />
{children}
</div>
)
}Пропсы: color (по умолчанию #2563eb), height (2 px), delay (мс — не
показывать для мгновенных переходов), zIndex.
Каталог навигации
Пункты меню собираются из маршрутов: задайте navigation — маршрут попадёт в
getNavigation(). Ключи (title, icon, order, права) — прикладные.
// client/AboutPage/router.ts
export default defineRoute([
{
id: 'about',
navigation: { title: 'О нас', order: 20 },
// ...
},
])import { getNavigation } from '@tusten/core'
const items = getNavigation() // [{ id: 'about', href: '/about', dynamic: false, title: 'О нас', order: 20 }]getNavigation()(«какие пункты есть») — неuseNavigation()(«где я сейчас»). Работает и на клиенте, и в серверном JSON-RPC-обработчике: можно вернуть каталог (например, уже отфильтрованный по правам) с сервера через обычныйService.call.- Статический маршрут получает
hrefиз пути; динамическому (/blog/:id) нужен явныйnavigation.href, иначе он отдаётся сdynamic: trueбез ссылки. - Каталог возвращает все пункты: фильтрация по правам, сортировка и группировка остаются в приложении. Считайте фильтр в рендере, чтобы он обновился после логина.
navigationдолжен быть JSON-safe (функции/Date/классы — ошибка сборки). Для чистых тестов иsitemap.xmlестьbuildNavigation(routes).
Подробно — docs/Router.md.
JSON-RPC-объект
// server/users/Users.meta.ts
import { defineObject } from '@tusten/core/server'
import type { RpcContext } from '@tusten/core/server'
import * as v from 'valibot'
export default defineObject({
name: 'Users',
description: 'Пользователи',
methods: {
List: {
description: 'Список',
params: v.object({ limit: v.optional(v.number()) }),
handler: async (params, ctx) => {
return ctx.db.users.findMany({ take: params.limit })
},
},
Update: {
auth: true,
handler: async (params, ctx) => {
const updated = await ctx.db.users.update(params)
// ctx.stomp.message(...) — в разработке
return updated
},
},
},
})Конфиг
// tusten.config.ts
import { defineConfig } from '@tusten/core'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
ssr: true,
client: {
root: {
component: 'Page/Controller:Root',
container: {
tag: 'div',
id: 'app',
attributes: { class: 'theme-default', 'data-qa': 'main-container' },
},
},
components: {
error: 'shared/ErrorBoundary:ErrorBoundary',
loading: 'shared/Loading:Loading',
notFound: 'shared/NotFound:NotFound',
},
css: ['styles/main.css'],
},
server: {
routes: 'server/api/routes.ts',
plugins: 'server/plugins',
rpc: { enabled: true, url: '/service' },
},
i18n: { key: 'lang', defaultLocale: 'ru', locales: ['ru', 'en'] },
vite: { plugins: [tailwindcss()] },
})Все пути в client.* (components, root.component, root.container, css) — относительно clientDir, без ./: Page/Controller:Root, layouts/Main. Старый вид с ./ поддерживается и нормализуется при загрузке конфига.
client.layouts и client.rootElement удалены: если они есть в конфиге, загрузчик выведет предупреждение и проигнорирует их. Layout задаётся в defineRoute, контейнер — в client.root.container.
Полное описание всех полей, значений по умолчанию и ограничений —
docs/Config.md.
Статика и сжатие
export default defineConfig({
// Каталог статики рядом с client/ и server/. false — отключить.
publicDir: 'public',
server: {
// Сжатие включено по умолчанию; false — если сжимает прокси/CDN.
compress: { threshold: 1024, encodings: ['br', 'gzip'], ssr: true },
},
})public/отдаётся с корня сайта. В dev каталог обслуживает Vite, при сборке он копируется вdist/client, а prod-сервер раздаёт его ещё и из исходного пути — файл, добавленный без пересборки, тоже будет доступен. Entry-чанк и остальные ассеты хэшируются (assets/<name>-<hash>.js,assets/<name>-<hash>.<ext>) и получаютCache-Control: public, max-age=31536000, immutable; файлы изpublic/—no-cache(ревалидация после деплоя).- Предсжатие статики. Сборка кладёт рядом с текстовыми файлами (
js,css,html,json,svg,xml,txt,map— крупнее 1 КБ) готовые.br(brotli quality 11) и.gz(gzip level 9). Prod-сервер включает@fastify/static.preCompressed: trueи отдаёт их поAccept-Encodingбез сжатия на каждый запрос;Vary: Accept-Encodingвыставляет сам плагин. Dev-режим не предсжимает — HMR важнее. server.compressпо умолчанию включён:@fastify/compressсжимаетPOST /service, API-роуты и статику, а SSR-документ и готовые HTML-тела (SPA-shell, 404, страницы ошибок) — встроенный zlib-пайплайн, потому что SSR пишет вreply.rawв обход хуков Fastify. Кодировка выбирается поAccept-Encoding,Vary: Accept-Encodingдобавляется к существующемуVary(i18n).ssr: falseоставляет сжатие API/статики, но отключает сжатие SSR-стрима;server.compress: falseвыключает всё. Предсжатые.br/.gzи@fastify/compressне конфликтуют: уже сжатый ответ плагин не трогает.
Алиасы путей
Источник правды — compilerOptions.paths в tsconfig.json:
{
"compilerOptions": {
"paths": {
"@/*": ["./client/*"],
"@server/*": ["./server/*"]
}
}
}Чтобы Vite их видел, включите vite.resolve.tsconfigPaths:
export default defineConfig({
vite: { resolve: { tsconfigPaths: true } },
})Серверный код (server.routes, server.plugins, middleware, RPC-объекты, configLoader и router.ts) фреймворк грузит через jiti — он читает те же paths, поэтому @server/… работает и в dev, и в prod-сборке. tsc, редактор, Vite и Node резолвят алиасы одинаково.
i18n
Локализация клиентских модулей. Словари лежат рядом с модулем:
client/HomePage/lang/ru/ru.json # основной язык — ключи (текст на исходном языке)
client/HomePage/lang/en/en.json// tusten.config.ts
export default defineConfig({
// key — имя cookie с выбранным языком; по умолчанию `lang`.
i18n: { key: 'lang', defaultLocale: 'ru', locales: ['ru', 'en'] },
})import rk from 'i18n!HomePage'
import { template, getLocale, setLocale } from '@tusten/core/client'
rk('Помощь') // перевод из lang/<locale>/<locale>.json
rk('Помощь', 'Поддержка') // сначала ищется "Поддержка@@Помощь"
template(rk('Привет, {name}!'), { name }) // интерполяция
template(rk('{n, plural, one {# файл} few {# файла} other {# файлов}}'), { n })
getLocale() // текущая locale (string | undefined)
setLocale('en') // cookie (имя из `i18n.key`, по умолчанию `lang`) + перезагрузка страницы- Нет словаря или ключа — возвращается исходный ключ, без ошибок. Битый JSON и нестроковое значение — ошибка сборки.
template()— подмножество ICU:{name},plural(one/few/many/other,otherобязателен), точное=N,#→ число. Экранирование —\{,\},\#,\\.- Locale: cookie
i18n.key(по умолчаниюlang) →Accept-Language(с учётомq, только изlocales) →defaultLocale. На сервере locale хранится вAsyncLocalStorage, поэтому параллельные запросы не смешивают языки. - Имя cookie валидируется при загрузке конфига (token по RFC 6265, обрезается по краям): пустая строка и недопустимые символы —
TustenError. Миграция с beta.5: дефолт сменился сtusten_localeнаlang; чтобы сохранить старое имя —i18n: { key: 'tusten_locale', ... }. - SSR, SPA и 404 рендерят
<html lang="…">с locale запроса; при выключенном i18n атрибут не выводится. - Словари использованных модулей уходят в HTML вместе с SSR; при SPA-навигации догружаются отдельным чанком вместе с маршрутом.
- Синтаксис импорта — только
i18n!<Module>;i18n:<Module>— внутренний virtual module. Типы подключаются через@tusten/core/client(или@tusten/core/i18n, если React не нужен). - Тесты: в
vitest.config.tsподключитеi18nTestPlugin()из@tusten/core/server—rk(key)вернётkey. tusten inspectпоказывает модули, число ключей по locale и отсутствующие словари.
Root controller
Компонент-оболочка приложения, которая рендерится всегда: SSR, гидрация, SPA-loading, ошибка и 404. Один раз на приложение — не нужно оборачивать каждый маршрут.
// tusten.config.ts
export default defineConfig({
client: {
root: {
component: 'Page/Controller:Root',
container: { tag: 'div', id: 'app' },
},
},
})// client/Page/Controller.tsx
import type { RootControllerProps } from '@tusten/core/client'
export function Root({ children, route, status }: RootControllerProps): JSX.Element {
return (
<AppProviders route={route}>
<Header />
{children}
<Footer />
</AppProviders>
)
}- Пропсы:
children(layout chain или Loading/Error/NotFound),route(TustenClientRoute | null),router,status(ready/loading/error/not-found),error. route— одна и та же проекция на сервере и клиенте; для потомков естьuseRoute().statusотражает состояние: initial SPA-prefetch (loading), ошибка навигации/prefetch (error), 404 (not-found).- Корень не перемонтируется при SPA-навигации: контекст, тема и открытые меню живут. Страница перемонтируется при смене URL.
- Ошибки страницы рендерит
components.errorвнутри корня; фатальные — dev-оверлей / prod-500. route.layoutнеобязателен: без него маршрут наследует цепочку родителя (parentId) или рендерится без layout'ов.client.layoutsбольше нет — layout объявляется вdefineRoute.RootErrorBoundaryсбрасывает пойманную ошибку при навигации (resetKey).
Layouts
Layout — это часть маршрута, как template. Глобального реестра client.layouts нет.
// client/HomePage/router.ts
export default defineRoute([{ id: 'home', index: true, layout: 'layouts/Main' /* ... */ }])Семантика route.layout:
| Значение | Результат |
| ----------------------------------- | ------------------------------------------------------------- |
| undefined | наследуется цепочка родителя (parentId); у корневого — [] |
| 'layouts/Main' | только этот layout (заменяет унаследованную цепочку) |
| ['layouts/Main', 'layouts/Admin'] | явная вложенность root → leaf |
| false или [] | без layout'ов (в том числе сброс унаследованного) |
- Спека — путь относительно
clientDirв формате<file>:<export>или<file>для default-export:Page/Layout:Main,layouts/Main. - Общие layout'ы удобно держать в TS-константах (
export const MAIN_LAYOUT = 'layouts/Main'), а не в конфиге. - Дубликаты подряд удаляются:
['layouts/Main', 'layouts/Main']→['layouts/Main'].
Контейнер приложения
По умолчанию SSR отдаёт <div id="root" data-tusten-root>. Тег, id и атрибуты настраиваются в client.root.container:
// tusten.config.ts
export default defineConfig({
client: {
root: {
container: {
tag: 'app-root', // вместо div; можно любой обычный/custom-тег
id: 'app', // по умолчанию 'root'; false — без id
attributes: { class: 'app-shell', 'data-theme': 'light' },
},
},
},
})data-tusten-root— служебный маркер: по нему клиент находит контейнер, поэтому менятьidиtagбезопасно.attributesпринимает строки, числа иtrue(boolean-атрибут, напримерhidden).false/undefinedпропускаются,on*запрещены — это статичный HTML, не обработчики.id: falseубирает id; клиент всё равно найдёт контейнер поdata-tusten-root.- Совсем без элемента нельзя: React нужен контейнер для
hydrateRoot/createRoot, а boot-скрипты живут в<body>. Ноtag: 'app-root'/section/custom element убирает лишнийdiv.
Ошибки в браузере (dev)
В dev ошибка не теряется в консоли:
- Падение SSR — отдельная страница с описанием, стеком и code frame. Стек маппится по sourcemap (
vite.ssrFixStacktrace), поэтому в кадрах исходные.tsx, а не результат трансформации; клик по кадру открывает файл в редакторе. - Ошибка после отправки shell (стриминг) — ошибки собираются в HTML (
window.__TUSTEN_SSR_ERRORS__) и показываются оверлеем поверх частично отрендеренной страницы. - Клиент — оверлей с описанием, стеком, кнопкой «Скопировать» и переходом в редактор: гидрация, SPA-навигация, initial prefetch и ошибки, пойманные
RootErrorBoundary(наличие fallback не скрывает баг). - SPA-навигация больше не «молчит»: если
loadDataили чанк маршрута упали, рендеритсяcomponents.error, а в dev дополнительно поднимается оверлей.
Оверлей — отдельная точка входа @tusten/core/client/dev-overlay: клиентский entry импортирует её только внутри if (import.meta.env.DEV), поэтому в production-бандл её код не попадает.
В production:
- 500-страница без стека и путей, с коротким «Кодом ошибки»;
- тот же код пишется в лог —
[tusten] SSR error [1a2b3c4d]: …— по нему находится конкретный запрос; - фатальный сбой клиента в SPA (без SSR) показывает «Не удалось загрузить страницу. Обновите её» вместо пустого экрана.
🏗 Архитектура
┌─────────────────────── Браузер ───────────────────────┐
│ │
│ client/*/router.ts ──► defineRoute([...]) │
│ client/*/Factories ──► getConfig → Service │
│ client/*/view.tsx ───► useSlice / useNavigation / <Link> │
│ usePageMeta │
│ │
└─────────────────┬──────────────────────────────────────┘
│ HTTP / WebSocket
▼
┌────────────────── Fastify ────────────────────────────┐
│ │
│ POST /service ← JSON-RPC 2.0 (defineObject) │
│ GET /stomp ← WebSocket (в планах) │
│ GET /api/* ← defineServerRoutes │
│ GET /* ← SSR / SPA HTML + meta │
│ │
│ ── при SSR: Service.call идёт через ALS executor ── │
│ (прямой вызов handler'а из реестра, без HTTP) │
│ │
└────────────────────────────────────────────────────────┘Ключевые архитектурные решения:
loadDataизоморфный — работает на сервере и клиенте, толькоfetch('/api/...')илиService.call(...). Никаких прямых обращений к БД, никаких Server Actions.- JSON-RPC для чтения и мутаций — единый протокол, типизация через Standard Schema,
ctx.callдля композиции методов. metaConfig+resolveMeta— meta резолвится параллельно с prefetch (Promise.all), поэтому SSR latency = max(prefetch, meta), не сумма.- SPA-переход атомарный — page-слайсы новой страницы прогреваются в отдельном
SliceRegistryи подменяют старые (adoptPage) только после успешныхloadData+ загрузки шаблона. Новое дерево рендерится вstartTransition, а слайсы старой страницы уничтожаются после commit — до этого она остаётся рабочей. Ошибка → остаёмся на текущей странице с живыми слайсами; global-слайсы переживают переход. - i18n на SSR — locale определяется по cookie /
Accept-Language, словари реально использованных модулей встраиваются в HTML доhydrateRoot;Vary: Accept-Language, Cookieне даёт кэшу смешать языки. - Безопасные SSR-ответы —
Cache-Control: no-storeна HTML, JSON-404 и редиректах;VaryучитываетAcceptдля контент-негоциации. - Быстрая доставка —
modulepreloadдля entry-чанка, чанка маршрута и слайсов; независимые фабрики, layout и Error-компонент грузятся параллельно; HTTP-ответы сжимаются по умолчанию (brotli/gzip), хэшированные ассеты кэшируются на год, статика ещё и предсжата на сборке. ctx.stomp.message(key, payload)— real-time push (в разработке).- Три реестра middleware — не смешиваются, каждый со своим контекстом.
@tusten/core/@tusten/core/server/@tusten/core/client— client-safe разделение,@tusten/coreне тянет Node.- 663 unit-теста (Vitest, 49 файлов) — ядро покрыто на 90%+.
📂 Структура репозитория
tusten-framework/
├── packages/
│ └── tusten/ # пакет @tusten/core
│ ├── src/
│ │ ├── index.ts # @tusten/core (client-safe)
│ │ ├── server.ts # @tusten/core/server (Node-only)
│ │ ├── client/ # @tusten/core/client (React, slices, hooks, i18n)
│ │ ├── shared/ # prefetch, meta-resolver, locale (изоморфный)
│ │ ├── server/ # Fastify, SSR, RPC, i18n (ALS)
│ │ ├── build/ # build pipeline
│ │ └── vite/ # Vite-плагин (virtual modules)
│ ├── types/ # ambient-типы i18n!*
│ ├── scripts/ # postbuild (d.ts для i18n)
│ ├── CHANGELOG.md # история изменений (источник истины)
│ └── README.md # генерируется из корневого (prepack)
│
├── examples/
│ └── basic/ # демо на Tailwind v4
│ ├── client/ # Home / About / Blog / Admin, i18n (ru/en)
│ ├── server/ # API + JSON-RPC meta
│ └── tusten.config.tsДокументация фреймворка — README.md (этот файл). Там всё: API, схемы, подводные камни, roadmap.
🗺 Roadmap
✅ Готово
- Phase 1 — SSR, SPA, prod build, CSS (Tailwind / per-component), enriched
_initState - Phase 2 —
defineServerRoutes,defineServerPlugins, 3 реестра middleware,useRouter/<Link>, JSON-RPC 2.0 (/service),Serviceс ALS executor - Phase 3 — динамические сегменты (
slug/path), вложенные layouts поparentId, per-routessr: false, error boundaries / loading / notFound - Phase 4 —
System.Describe, рекурсивный CSS-scan,devalue(Map/Date/ cyclic), cross-page кэш вService(LRU,cacheMaxEntries) - Phase 5 — 425 unit-тестов (Vitest), GitHub Actions CI (
format:check+lint+typecheck+test), Prettier + ESLint, публикация@tusten/[email protected]в npm - Phase 6 — SEO / meta:
metaConfig(статика),readMethod(JSON-RPC),getMetaCallback(функция),usePageMeta(client),microdata(JSON-LD),resolveMeta(SSR, параллельно с prefetch) - Phase 7 — i18n клиентских модулей (
i18n!<Module>, словари по locale,template()с ICU-plural, SSR-гидрация без mismatch, locale в ALS) и доработка слайсов по мотивам DataEnv (destroy/isDestroyed,_initState(result, config), сериализацияconfig, мержsetState,getDataFactoryArguments, атомарныйadoptPage), публикация@tusten/[email protected]в npm - Phase 8 —
create-tusten-app, каталог навигации (getNavigation), сжатие и предсжатие ответов,publicDir, хэшированные ассеты,startTransition+pending, алиасы изtsconfig.json, опциональныйprefetchConfig; релиз@tusten/[email protected]и[email protected]
🚧 В разработке
- STOMP-слой —
ctx.stomp.message(key, payload)+useStomp(key, fn)+ автопереподключение (дизайн готов)
📋 Запланировано
- Пресеты (
defineConfig({ preset: 'tailwind' })) - Сайт документации (сам tusten на tusten)
tusten i18n extract— сканrk(...)через TS AST и типизированные ключиsliceExtraValues/loaderExtraValues— реактивные связи между слайсами (DataEnv, P2)- Тесты для
ssr-handler.ts,create-server.ts,vite/plugin.ts(Vite mock +inject) - Redis-adapter для STOMP (PM2 / cluster)
- Auto-invalidate при мутациях (
create/update/destroy→ сбросList) @fastify/rate-limitна/service+ CSRF-защита- Мемоизация
useParams/useQuery <Link prefetch>—onTouchStartдля мобильных<link rel="canonical">иalternatesвmetaConfig- Множественные
<meta>с одинаковымname(Open Graph galleries)
❌ Не планируется
- React Server Components — осознанно. Другая архитектура, месяцы работы, ломает
Slice/loadData/defineObject. - Server Actions — осознанно. JSON-RPC +
Service.callпокрывает мутации.
🛠 Разработка
# Установка
pnpm install
# Проверки
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
# Dev-сервер демо
pnpm dev:basic
TUSTEN_DEBUG=1 pnpm dev:basic # + логи __ROOT_STATE_STR__
# Prod
pnpm build:basic
pnpm start:basic
# Дамп маршрутов и RPC-методов
pnpm inspect:basic
# Публикация
pnpm publish:alpha
pnpm publish:beta
pnpm publish:latestТребования
- Node.js ≥ 20
- pnpm ≥ 9 (через
corepack enable)
Стиль кода
- Весь код документирован JSDoc (
@param,@returns,@throws). - Framework
.tsx— черезcreateElement, не JSX (иначе jiti ломает classic runtime). - User
.tsx— обычный JSX через Vite. - Не-тривиальная логика — inline-комментарии (почему, а не что).
Подводные камни (для контрибьюторов)
Перед правкой vite/plugin.ts или server/ssr-handler.ts прочитайте раздел «Подводные камни» ниже. Особенно:
RootProvider/SliceRegistry/devalueParse— только черезvite.ssrLoadModule(dev) /dist/server/entry.js(prod).@tusten/coreне должен тянуть Node-зависимости.- После правок
plugin.ts/serialize.ts— всегдаrm -rf examples/basic/node_modules/.vite. - Всё, что
create-server.tsпередаёт в Vite-плагин, должен передавать иbuild-client.ts/build-server.ts(иначе dev ≠ prod). - Windows:
import(absolutePath)требуетpathToFileURL()— иначеERR_UNSUPPORTED_ESM_URL_SCHEME. - Тесты: мутации слайса (
slice.setState,registry.setPage) послеrender()— только вact(). resolveMetaрезолвится параллельно сrunPagePrefetch(Promise.all) — не переделывать в sequential, это удвоит SSR latency.getMetaCallback-пути должны быть добавлены вspecToPath/allSsrSpecsв Vite-плагине, иначеresolveModuleих не найдёт.- i18n-модули (
i18n!<Module>,i18n:<Module>,i18n-dict:*) — только virtual modules Vite-плагина. В серверном коде и через jiti их импортировать нельзя. - Locale SSR-запроса — только
AsyncLocalStorage; глобальная переменная смешает языки параллельных запросов. Vary: Accept-Language, Cookieна SSR-ответах обязателен при включённом i18n, иначе кэш отдаст чужой язык.- Пути модулей канонизируются через
realpathSync.native(resolveRealPath): на Windows/macOS иначе HMR не видит правку при другом регистре в спеке ('HomePage/view'↔View.tsx).
❓ Зачем ещё один фреймворк
Потому что:
- Next.js тянет RSC и Server Actions — мощно, но сложно. Если они не нужны, платите за них bundle size, когнитивной нагрузкой и временем сборки.
- Nuxt — Vue. Отличный, но если вы на React — не подходит.
- Astro — контент-фреймворк. Для дашбордов и админок неудобен.
- React Router 7 / Remix — ментальная модель другая (loader'ы в route-модулях, actions, form-first). Не всем подходит.
tusten — для тех, кому нужен:
- React 19 + Fastify + Vite — три понятных инструмента, без магии.
- JSON-RPC вместо REST — типизированный, валидируемый, batch-friendly.
- Изоморфный
loadData— один код на сервере и клиенте, толькоfetch('/api/...'). Sliceвместо Redux/Zustand — встроенный, per-route, auto-destroy.- Client-safe разделение —
@tusten/core(pure),@tusten/core/server(Node),@tusten/core/client(React). Явно, без сюрпризов. - Контроль — не «чёрный ящик», а ~8 000 строк читаемого TypeScript (ядро + тесты).
Если узнали себя — попробуйте демо.
🧪 Стабильность API
Фреймворк в статусе beta. Это значит:
Что может измениться без предупреждения
- Публичный API — сигнатуры
defineRoute,defineGlobalLoader,defineObject,Service,Slice, хуков (useSlice,useNavigation,usePageMeta), i18n (rk,template,getLocale,setLocale). - Формат конфига (
tusten.config.ts) — поля могут переименовываться, получать новые опции, менять дефолты;i18nтоже входит сюда. - Схема маршрута (
TustenRoute) —path,slug,ssr,middleware,metaConfig,contentConfigи т.д. - JSON-RPC — wire-протокол, формат
System.Describe, коды ошибок. - Meta:
MetaTag,MetaResult,MetaConfig,PageMeta— форма может расширяться. - Внутренние детали, которые просачиваются наружу:
__ROOT_STATE_STR__,__ROOT_MIDDLEWARE__,__ROOT_I18N__,virtual:tusten/*,i18n:*/i18n-dict:*,dist/server/entry.js. - Поведение — например, дефолтный
cacheMaxEntriesвServiceможет измениться.
Что стабилизируется раньше
defineConfig— базовая структура (ssr,client,server) может изменится.defineRoute— структура маршрута (id, parentId, type, metaConfig) — фундаментальная.Slice/AbstractSlice—hydrate(result, config),state,setState,subscribe,destroy— ядро реактивности.loadData(args, deps, ctx)— сигнатура.MetaTag—{ name, content, attribute? }.- i18n-контракт —
rk(key, ctx?)→string,template(str, params, locale?)→string, словариlang/<locale>/<locale>.json.
Философия версионирования
0.x.y(alpha / beta) — API стабилизируется, breaking changes возможны в минорных версиях, но редко.0.x.0— обязательно breaking changes (например,0.2.0→0.3.0).0.x.y(patch) — багфиксы, без breaking.1.0.0— первый стабильный релиз. После — semver: breaking changes только в мажорных версиях.
Как отслеживать
- GitHub Releases — каждое изменение, помеченное
BREAKINGилиfeat. packages/tusten/CHANGELOG.md— полная история изменений (Keep a Changelog + SemVer).README.md— актуальная документация.
Если вы уже используете tusten
- Читайте Release Notes перед
pnpm update @tusten/core. - Фиксируйте точную версию в проде —
pnpm add @tusten/[email protected](не@beta). - Пишите обёртки над публичным API — если сигнатура изменится, поправите в одном месте.
- Сообщайте о проблемах — Issues помогают стабилизировать API раньше.
📄 Лицензия
MIT © 2026 yartema
