@ivlev-dev/silent-vite 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +164 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,164 @@
1
+ # @ivlev-dev/silent-vite
2
+
3
+ Vite-плагин Silent Framework: компиляция TS/TSX/JS/JSX через нативный addon `@ivlev-dev/silent-swc`, автоматический индекс DI и HMR с сохранением состояния.
4
+
5
+ ![npm version](https://img.shields.io/npm/v/@ivlev-dev/silent-vite)
6
+ ![license](https://img.shields.io/npm/l/@ivlev-dev/silent-vite)
7
+ ![vite](https://img.shields.io/badge/vite-%3E%3D8-blue)
8
+
9
+ ## Возможности
10
+
11
+ - Компиляция TypeScript, TSX, JS и JSX нативным addon'ом на Rust + `swc_core` — быстрее, чем чисто JavaScript-транспиляторы.
12
+ - Compile-time DI: плагин сканирует проект и передаёт компилятору индекс интерфейсов и реализаций, конструкторы разрешаются без ручных `bind`.
13
+ - HMR из коробки: `import.meta.hot.accept` внедряется на этапе компиляции, состояние ViewModel и сигналов переживает правки.
14
+ - Source maps передаются в Vite как есть из addon'а.
15
+ - Тонкая настройка: опции SWC, шаблоны `include`/`exclude`, корень проекта, имя рантайм-модуля.
16
+ - Работает с `enforce: "pre"` — хуки выполняются раньше стандартных плагинов Vite.
17
+
18
+ ## Установка
19
+
20
+ Плагин **не содержит рантайма**. Для работы приложения обязательно нужен пакет `@ivlev-dev/silent-core` — он устанавливается в `dependencies` и тянет за собой `@ivlev-dev/silent-di` и `@ivlev-dev/silent-reactivity`. Сам плагин и `vite` идут в `devDependencies`.
21
+
22
+ Установки только `@ivlev-dev/silent-vite` недостаточно: без `@ivlev-dev/silent-core` приложение не соберётся и не запустится.
23
+
24
+ ```bash
25
+ pnpm add @ivlev-dev/silent-core
26
+ pnpm add -D @ivlev-dev/silent-vite vite
27
+ ```
28
+
29
+ ## Быстрый старт
30
+
31
+ `vite.config.ts`:
32
+
33
+ ```ts
34
+ import { defineConfig } from "vite";
35
+ import { silent } from "@ivlev-dev/silent-vite";
36
+
37
+ export default defineConfig({
38
+ plugins: [silent()],
39
+ });
40
+ ```
41
+
42
+ `tsconfig.json` — JSX компилируется рантаймом Silent Framework:
43
+
44
+ ```json
45
+ {
46
+ "compilerOptions": {
47
+ "jsx": "react-jsx",
48
+ "jsxImportSource": "@ivlev-dev/silent-core"
49
+ }
50
+ }
51
+ ```
52
+
53
+ `index.html`:
54
+
55
+ ```html
56
+ <!doctype html>
57
+ <html lang="ru">
58
+ <head>
59
+ <meta charset="UTF-8" />
60
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
61
+ <title>Silent Framework</title>
62
+ </head>
63
+ <body>
64
+ <div id="app"></div>
65
+ <script type="module" src="/src/main.tsx"></script>
66
+ </body>
67
+ </html>
68
+ ```
69
+
70
+ `src/main.tsx`:
71
+
72
+ ```tsx
73
+ import { mount } from "@ivlev-dev/silent-core";
74
+ import { App } from "./app";
75
+
76
+ void mount("#app", App, { props: { title: "Silent Framework" } });
77
+ ```
78
+
79
+ `mount` возвращает `Promise<MountHandle>` с `ready` и `dispose()`. Для SSR используйте `hydrate` из `@ivlev-dev/silent-core` вместо `mount`.
80
+
81
+ ## Опции
82
+
83
+ Все опции `silent(options?)` необязательны.
84
+
85
+ | Опция | Тип | По умолчанию | Описание |
86
+ | --- | --- | --- | --- |
87
+ | `include` | `RegExp` | `/\.(ts\|tsx\|mts\|cts\|js\|jsx\|mjs\|cjs)$/` | Файлы, подлежащие компиляции. |
88
+ | `exclude` | `RegExp` | `/node_modules/` | Файлы, исключаемые из компиляции. |
89
+ | `root` | `string` | `process.cwd()` | Корень проекта; файлы вне его не трансформируются. |
90
+ | `swc` | `Record<string, unknown>` | `{}` | Опции компилятора SWC, передаются в addon как есть. По умолчанию компиляция идёт с `target: "es2024"`; JSX всегда компилируется рантаймом Silent Framework. |
91
+ | `requirePreloader` | `boolean` | `false` | Требовать прелоадер на уровне view. |
92
+ | `runtime` | `string` | `"@ivlev-dev/silent-core"` | Имя рантайм-модуля для сгенерированного кода. |
93
+ | `hmr` | `boolean` | `true` | Внедрять HMR-код в компилируемые модули. |
94
+ | `index` | `boolean` | `true` | Строить индекс DI по файлам проекта. При `false` передаётся пустой индекс и scan не вызывается. |
95
+
96
+ Пример с нестандартными опциями:
97
+
98
+ ```ts
99
+ silent({
100
+ include: /\.(ts|tsx|js|jsx)$/,
101
+ exclude: /node_modules/,
102
+ swc: {
103
+ jsc: { target: "es2020" },
104
+ },
105
+ hmr: true,
106
+ index: true,
107
+ });
108
+ ```
109
+
110
+ ## Как это работает
111
+
112
+ Плагин работает с `enforce: "pre"`, поэтому его хуки выполняются раньше остальных.
113
+
114
+ 1. **`buildStart`** — при `index: true` нативный addon сканирует `root` и строит индекс DI: `SilentIndex = { interfaces: Record<string, string[]>; values: Record<string, string[]> }`. Индекс сериализуется в JSON и кешируется в памяти.
115
+ 2. **`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`) и подставляет реализации интерфейсов из индекса при компиляции конструкторов.
116
+ 3. **`watchChange` / `handleHotUpdate`** — при изменении исходного (не виртуального) модуля кеш индекса DI сбрасывается и перестраивается при следующем запросе.
117
+
118
+ - **Source maps**: addon возвращает `map: string | null`, плагин передаёт его в Vite без изменений.
119
+ - **Диагностики**: поле `diagnostics` addon'а возвращается Vite как warnings результата `transform`.
120
+ - **Режимы dev/prod**: плагин не ветвится по режиму — трансформация применяется всегда; HMR-код активен только в dev, где существует `import.meta.hot`.
121
+
122
+ ## HMR
123
+
124
+ В dev-режиме компилятор по флагу `hmr` внедряет `import.meta.hot.accept` в компилируемые модули. Состояние переживает правки:
125
+
126
+ - **Изменение view (компонента)** — ViewModel и значения сигналов сохраняются; для каждого инстанса вызывается `rerender`.
127
+ - **Изменение модуля ViewModel** — создаётся новый экземпляр со переносом значений `@reactive`-полей; при наличии новой функции прелоадера обновляется и он.
128
+ - **Несовместимые изменения** — выполняется `import.meta.hot.invalidate()` и полная перезагрузка затронутого модуля.
129
+ - **Обновление рантайма фреймворка** — всегда полная перезагрузка.
130
+
131
+ Отладка:
132
+
133
+ - Реестр инстансов хранится на `globalThis` — инстансы VM можно осмотреть из консоли браузера.
134
+ - Ошибки addon'а приходят с префиксом `@ivlev-dev/silent-vite:` и именем файла; подробности SWC видны в `diagnostics`/`warnings` и stderr.
135
+ - Если при правке state сбрасывается — проверьте, менялись ли сигнатуры: migrations для VM не поддерживаются, логика `hmrUpdate`/`hmrInvalidate` переносит только совместимые структуры.
136
+
137
+ ## Ограничения и совместимость
138
+
139
+ - Vite версии не ниже 8 (peer dependency), Node.js не ниже 22 (`engines`).
140
+ - Обрабатываются только файлы по шаблону `include` внутри `root`; `node_modules` исключены по умолчанию.
141
+ - Нативный addon `@ivlev-dev/silent-swc` — зависимость плагина; без собранного бинарника `loadSwc()` выбрасывает ошибку с подсказкой пересобрать его. При несовпадении ABI пересоберите addon.
142
+ - Виртуальные модули (`\0…`, `virtual:…`) пропускаются.
143
+ - Индекс DI строится один раз за запуск и инвалидируется при изменении исходных модулей; правки `vite.config.ts` требуют перезапуска dev-сервера.
144
+ - В SSR-сборке держите рантайм внешним (`ssr.external`), иначе приложение получит вторую копию рантайма и гидрация не дождётся компонентов:
145
+
146
+ ```ts
147
+ export default defineConfig({
148
+ plugins: [silent()],
149
+ ssr: {
150
+ external: ["@ivlev-dev/silent-core", "@ivlev-dev/silent-di", "@ivlev-dev/silent-reactivity", "@ivlev-dev/silent-server"],
151
+ },
152
+ });
153
+ ```
154
+
155
+ ## Ссылки
156
+
157
+ - [Репозиторий silent-framework](https://github.com/ivlev-dev/silent-framework)
158
+ - [Документация API плагина](https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/vite.md)
159
+ - [CHANGELOG](https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md)
160
+ - [Issues](https://github.com/ivlev-dev/silent-framework/issues)
161
+
162
+ ---
163
+
164
+ MIT © ivlev-dev
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ivlev-dev/silent-vite",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "main": "./dist/index.js",
@@ -15,7 +15,7 @@
15
15
  "dist"
16
16
  ],
17
17
  "dependencies": {
18
- "@ivlev-dev/silent-swc": "0.1.1"
18
+ "@ivlev-dev/silent-swc": "0.1.2"
19
19
  },
20
20
  "peerDependencies": {
21
21
  "vite": ">=8"