@ivlev-dev/silent-vite
v0.12.0
Published
Vite plugin for Silent Framework with SWC compilation and HMR
Readme
@ivlev-dev/silent-vite
Vite-плагин Silent Framework: компиляция TS/TSX/JS/JSX через нативный addon @ivlev-dev/silent-swc, автоматический индекс DI и HMR с сохранением состояния.
Возможности
- Компиляция TypeScript, TSX, JS и JSX нативным addon'ом на Rust +
swc_core— быстрее, чем чисто JavaScript-транспиляторы. - Compile-time DI: плагин сканирует проект и передаёт компилятору индекс интерфейсов и реализаций, конструкторы разрешаются без ручных
bind. - HMR из коробки:
import.meta.hot.acceptвнедряется на этапе компиляции, состояние ViewModel и сигналов переживает правки. - Source maps передаются в Vite как есть из addon'а.
- Тонкая настройка: опции SWC, шаблоны
include/exclude, корень проекта, имя рантайм-модуля. - Работает с
enforce: "pre"— хуки выполняются раньше стандартных плагинов Vite.
Установка
Плагин не содержит рантайма. Для работы приложения обязательно нужен пакет @ivlev-dev/silent-core — он устанавливается в dependencies и тянет за собой @ivlev-dev/silent-di и @ivlev-dev/silent-reactivity. Сам плагин и vite идут в devDependencies.
Установки только @ivlev-dev/silent-vite недостаточно: без @ivlev-dev/silent-core приложение не соберётся и не запустится.
pnpm add @ivlev-dev/silent-core
pnpm add -D @ivlev-dev/silent-vite viteБыстрый старт
vite.config.ts:
import { defineConfig } from "vite";
import { silent } from "@ivlev-dev/silent-vite";
export default defineConfig({
plugins: [silent()],
});tsconfig.json — JSX компилируется рантаймом Silent Framework:
{
"compilerOptions": {
"jsx": "react-jsx",
"jsxImportSource": "@ivlev-dev/silent-core"
}
}index.html:
<!doctype html>
<html lang="ru">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Silent Framework</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>src/main.tsx:
import { mount } from "@ivlev-dev/silent-core";
import { App } from "./app";
void mount("#app", App, { props: { title: "Silent Framework" } });mount возвращает Promise<MountHandle> с ready и dispose(). Для SSR используйте hydrate из @ivlev-dev/silent-core вместо mount.
Опции
Все опции silent(options?) необязательны.
| Опция | Тип | По умолчанию | Описание |
| --- | --- | --- | --- |
| include | RegExp | /\.(ts\|tsx\|mts\|cts\|js\|jsx\|mjs\|cjs)$/ | Файлы, подлежащие компиляции. |
| exclude | RegExp | /node_modules/ | Файлы, исключаемые из компиляции. |
| root | string | process.cwd() | Корень проекта; файлы вне его не трансформируются. |
| swc | Record<string, unknown> | {} | Опции компилятора SWC, передаются в addon как есть. По умолчанию компиляция идёт с target: "es2024"; JSX всегда компилируется рантаймом Silent Framework. |
| requirePreloader | boolean | false | Требовать прелоадер на уровне view. |
| runtime | string | "@ivlev-dev/silent-core" | Имя рантайм-модуля для сгенерированного кода. |
| hmr | boolean | true | Внедрять HMR-код в компилируемые модули. |
| index | boolean | true | Строить индекс DI по файлам проекта. При false передаётся пустой индекс и scan не вызывается. |
| view | boolean | true | Включить view/VM-рантайм и lazy-чанк component-view. |
| hydrate | boolean | true | Включить клиентскую гидрацию. При false hydration-ветки и прокси вырезаются из стартового чанка. |
| di | "allow" \| "warn" \| "error" | "warn" | Политика DI-диагностик компилятора: игнорировать, выводить предупреждения Vite или ронять сборку. |
Пример с нестандартными опциями:
silent({
include: /\.(ts|tsx|js|jsx)$/,
exclude: /node_modules/,
swc: {
jsc: { target: "es2020" },
},
hmr: true,
index: true,
view: true,
hydrate: true,
di: "error",
});Как это работает
Плагин работает с enforce: "pre", поэтому его хуки выполняются раньше остальных.
buildStart— приindex: trueнативный addon сканируетrootи строит индекс DI:SilentIndex = { interfaces: Record<string, string[]>; values: Record<string, string[]> }. Индекс сериализуется в JSON и кешируется в памяти.transform— для каждого модуля id очищается от query и hash, пропускаются виртуальные модули (\0…,virtual:…), проверяютсяinclude,excludeи попадание вroot. Затем вызываетсяswc.transform(source, filename, optionsJson, indexJson)addon'а@ivlev-dev/silent-swc, который компилирует TS/TSX в JavaScript, внедряет HMR (import.meta.hot.accept) и подставляет реализации интерфейсов из индекса при компиляции конструкторов.watchChange/handleHotUpdate— при изменении исходного (не виртуального) модуля кеш индекса DI сбрасывается и перестраивается при следующем запросе.
- Source maps: addon возвращает
map: string | null, плагин передаёт его в Vite без изменений. - Диагностики: поле
diagnosticsaddon'а обрабатывается по политикеdi(см. ниже); вwarningsрезультатаtransformони не дублируются. - Режимы dev/prod: плагин не ветвится по режиму — трансформация применяется всегда; HMR-код активен только в dev, где существует
import.meta.hot.
Диагностика DI
Компилятор возвращает diagnostics, когда, например, для интерфейса не найдено реализации или найдено несколько реализаций. Опция di задаёт политику:
| Значение | Поведение |
| --- | --- |
| "allow" | Диагностики игнорируются. |
| "warn" (по умолчанию) | Каждая диагностика выводится через this.warn Vite (с префиксом [silent-vite] DI: ); warnings результата transform остаются пустыми. |
| "error" | transform выбрасывает Error с префиксом [silent-vite] DI: и списком диагностик — сборка падает с именем зависимости в тексте. |
silent({ di: "error" });Политика применяется одинаково для cache miss и cache hit: кешированный результат хранит те же diagnostics, поэтому ошибка воспроизводится и при повторной сборке из кеша cacheDir.
Статически компилятор проверяет интерфейсы и биндинги. Классы без DI_CREATE и без явного биндинга на этапе сборки не видны, поэтому дополнительно включите строгий режим контейнера — тогда неразрешённая зависимость падает в рантайме при создании контейнера:
import { Container } from "@ivlev-dev/silent-di";
const container = new Container("root", undefined, { implicitBindings: "error" });implicitBindings: "error" запрещает неявное создание классов и делает отсутствующую реализацию ошибкой, а не молчаливым undefined. Режим наследуется дочерними контейнерами и scope'ами. Рекомендуемая комбинация — di: "error" в плагине и строгий контейнер в рантайме.
HMR
В dev-режиме компилятор по флагу hmr внедряет import.meta.hot.accept в компилируемые модули. Состояние переживает правки:
- Изменение view (компонента) — ViewModel и значения сигналов сохраняются; для каждого инстанса вызывается
rerender. - Изменение модуля ViewModel — создаётся новый экземпляр со переносом значений
@reactive-полей; при наличии новой функции прелоадера обновляется и он. - Несовместимые изменения — выполняется
import.meta.hot.invalidate()и полная перезагрузка затронутого модуля. - Обновление рантайма фреймворка — всегда полная перезагрузка.
Отладка:
- Реестр инстансов хранится на
globalThis— инстансы VM можно осмотреть из консоли браузера. - Ошибки addon'а приходят с префиксом
@ivlev-dev/silent-vite:и именем файла; DI-диагностики выводятся по политикеdiс префиксом[silent-vite] DI:, подробности SWC видны в stderr. - Если при правке state сбрасывается — проверьте, менялись ли сигнатуры: migrations для VM не поддерживаются, логика
hmrUpdate/hmrInvalidateпереносит только совместимые структуры.
Ограничения и совместимость
- Vite версии не ниже 8 (peer dependency), Node.js не ниже 22 (
engines). - Обрабатываются только файлы по шаблону
includeвнутриroot;node_modulesисключены по умолчанию. - Нативный addon
@ivlev-dev/silent-swc— зависимость плагина; без собранного бинарникаloadSwc()выбрасывает ошибку с подсказкой пересобрать его. При несовпадении ABI пересоберите addon. - Виртуальные модули (
\0…,virtual:…) пропускаются. - Индекс DI строится один раз за запуск и инвалидируется при изменении исходных модулей; правки
vite.config.tsтребуют перезапуска dev-сервера. diуправляет только compile-time диагностиками: для классов безDI_CREATE/биндинга включите строгий режим контейнера (implicitBindings: "error").- В SSR-сборке держите рантайм внешним (
ssr.external), иначе приложение получит вторую копию рантайма и гидрация не дождётся компонентов:
export default defineConfig({
plugins: [silent()],
ssr: {
external: ["@ivlev-dev/silent-core", "@ivlev-dev/silent-di", "@ivlev-dev/silent-reactivity", "@ivlev-dev/silent-server"],
},
});Ссылки
MIT © ivlev-dev
