npm - @dxtmisha/wiki - Versions diffs - 0.56.0 → 0.57.1 - Mend

@dxtmisha/wiki 0.56.0 → 0.57.1

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 (79) hide show

package/src/media/functional/nitro-basic/setup/setup.ru.mdx ADDED Viewed

@@ -0,0 +1,133 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+<Meta title='@dxtmisha/ru/nitro-basic/# Подготовка проекта'/>
+# Подготовка проекта
+Библиотека `@dxtmisha/nitro-basic` спроектирована для работы в связке с Nitro и Vue 3. Она обеспечивает плавный переход между серверным и клиентским рендерингом. Ниже приведено пошаговое руководство по интеграции библиотеки в ваш проект.
+## 1. Установка зависимостей
+Установите необходимые пакеты. Помимо самой библиотеки, вам потребуются Vue 3 и Vue Router:
+```bash
+npm install @dxtmisha/nitro-basic vue vue-router
+```
+## 2. Инициализация плагина Nitro
+Для базовой настройки серверной среды (например, кэширования API) необходимо зарегистрировать плагин Nitro.
+Создайте файл `server/plugins/ui.ts`:
+```typescript
+import { definePlugin } from 'nitro'
+import { initPluginBasic } from '@dxtmisha/nitro-basic/plugin'
+export default definePlugin((nitroApp) => {
+  initPluginBasic(nitroApp)
+})
+```
+## 3. Создание фабрики приложения (main.ts)
+Создайте общий файл для инициализации Vue-приложения, который будет использоваться и на сервере, и на клиенте.
+```typescript
+// src/main.ts
+import { uiCreateApp } from '@dxtmisha/nitro-basic'
+import App from './App.vue'
+import { routes } from './router'
+export function createApp() {
+  return uiCreateApp(App, {
+    appRouter: {
+      routes
+    }
+  })
+}
+```
+## 4. Настройка клиентской точки входа
+На клиенте необходимо подготовить генератор идентификаторов и примонтировать приложение.
+```typescript
+// src/entry-client.ts
+import { uiBootstrapClient, uiCreateClientApp } from '@dxtmisha/nitro-basic'
+import { createApp } from './main'
+const { app, router, options } = createApp()
+// Инициализация ID для гидратации
+uiBootstrapClient()
+// Монтирование приложения
+uiCreateClientApp(app, '#app', router, options)
+```
+## 5. Настройка серверной точки входа
+Серверная точка входа отвечает за инициализацию хранилищ, заголовков и рендеринг HTML.
+```typescript
+// src/entry-server.ts
+import { uiBootstrapServer, uiCreateServerApp } from '@dxtmisha/nitro-basic'
+import { createApp } from './main'
+import template from './templates/main.html?raw' // HTML шаблон
+// Глобальная инициализация сервера
+uiBootstrapServer()
+export default {
+  async fetch(request: Request) {
+    const { app, router, options } = createApp()
+    const { headers, body } = await uiCreateServerApp(
+      app,
+      request,
+      router,
+      options,
+      undefined,
+      undefined,
+      template
+    )
+    return new Response(body, { headers })
+  }
+}
+```
+## 6. HTML Шаблон
+Для корректной работы SSR библиотека использует систему плейсхолдеров в HTML-шаблоне. Функция `uiCreateServerApp` автоматически заменяет их актуальными данными.
+**Доступные метки:**
+- `<!--ssr-lang-->` — языковой код пользователя (например, `ru`). Используется в `<html lang="...">`.
+- `<!--ssr-title-->` — заголовок страницы из `MetaStatic`. Подставляется в `<title>`.
+- `<!--ssr-meta-->` — блок мета-тегов (OG, Twitter и др.) из `MetaStatic`.
+- `<!--ssr-outlet-->` — отрендеренный HTML вашего приложения. Обычно внутри `<div id="app">`.
+- `<!--ssr-teleports-->` — содержимое Vue Teleports.
+- `<!--ssr-scriptsJson-->` — **Критически важная метка**. Содержит JSON с данными для гидратации (`ServerStorage`, кэш API). Должна быть размещена перед закрывающим `</body>`.
+Пример `main.html`:
+```html
+<!DOCTYPE html>
+<html lang="<!--ssr-lang-->">
+<head>
+    <meta charset="UTF-8">
+    <!--ssr-meta-->
+    <title><!--ssr-title--></title>
+</head>
+<body>
+    <div id="app"><!--ssr-outlet--></div>
+    <!--ssr-teleports-->
+    <!--ssr-scriptsJson-->
+    <script type="module" src="/src/entry-client.ts"></script>
+</body>
+</html>
+```
+> Без метки `<!--ssr-scriptsJson-->` данные, полученные на сервере, не будут переданы на клиент, что приведет к ошибкам гидратации и повторным запросам к API.

package/src/media/functional/nitro-basic/setup/setup.vi.mdx ADDED Viewed

@@ -0,0 +1,133 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+<Meta title='@dxtmisha/vi/nitro-basic/# Chuẩn bị dự án'/>
+# Chuẩn bị dự án
+Thư viện `@dxtmisha/nitro-basic` được thiết kế để hoạt động kết hợp với Nitro và Vue 3. Nó đảm bảo sự chuyển đổi mượt mà giữa quá trình render phía server và phía client. Dưới đây là hướng dẫn từng bước để tích hợp thư viện vào dự án của bạn.
+## 1. Cài đặt các phần phụ thuộc
+Cài đặt các gói cần thiết. Ngoài bản thân thư viện, bạn sẽ cần Vue 3 và Vue Router:
+```bash
+npm install @dxtmisha/nitro-basic vue vue-router
+```
+## 2. Khởi tạo Plugin Nitro
+Để thiết lập môi trường server cơ bản (ví dụ: lưu đệm API), bạn cần đăng ký một plugin Nitro.
+Tạo tệp `server/plugins/ui.ts`:
+```typescript
+import { definePlugin } from 'nitro'
+import { initPluginBasic } from '@dxtmisha/nitro-basic/plugin'
+export default definePlugin((nitroApp) => {
+  initPluginBasic(nitroApp)
+})
+```
+## 3. Tạo Factory ứng dụng (main.ts)
+Tạo một tệp dùng chung để khởi tạo ứng dụng Vue sẽ được sử dụng trên cả server và client.
+```typescript
+// src/main.ts
+import { uiCreateApp } from '@dxtmisha/nitro-basic'
+import App from './App.vue'
+import { routes } from './router'
+export function createApp() {
+  return uiCreateApp(App, {
+    appRouter: {
+      routes
+    }
+  })
+}
+```
+## 4. Cấu hình điểm đầu vào Client
+Trên client, bạn cần chuẩn bị trình tạo định danh và mount ứng dụng.
+```typescript
+// src/entry-client.ts
+import { uiBootstrapClient, uiCreateClientApp } from '@dxtmisha/nitro-basic'
+import { createApp } from './main'
+const { app, router, options } = createApp()
+// Khởi tạo ID để hydrat hóa
+uiBootstrapClient()
+// Mount ứng dụng
+uiCreateClientApp(app, '#app', router, options)
+```
+## 5. Cấu hình điểm đầu vào Server
+Điểm đầu vào server chịu trách nhiệm khởi tạo bộ lưu trữ, header và render HTML.
+```typescript
+// src/entry-server.ts
+import { uiBootstrapServer, uiCreateServerApp } from '@dxtmisha/nitro-basic'
+import { createApp } from './main'
+import template from './templates/main.html?raw' // HTML template
+// Khởi tạo server toàn cục
+uiBootstrapServer()
+export default {
+  async fetch(request: Request) {
+    const { app, router, options } = createApp()
+    const { headers, body } = await uiCreateServerApp(
+      app,
+      request,
+      router,
+      options,
+      undefined,
+      undefined,
+      template
+    )
+    return new Response(body, { headers })
+  }
+}
+```
+## 6. Template HTML
+Để SSR hoạt động chính xác, thư viện sử dụng một hệ thống nhãn (placeholder) trong template HTML. Hàm `uiCreateServerApp` sẽ tự động thay thế chúng bằng dữ liệu thực tế.
+**Các nhãn khả dụng:**
+- `<!--ssr-lang-->` — mã ngôn ngữ của người dùng (ví dụ: `vi`). Được sử dụng trong `<html lang="...">`.
+- `<!--ssr-title-->` — tiêu đề trang từ `MetaStatic`. Được chèn vào `<title>`.
+- `<!--ssr-meta-->` — khối các thẻ meta (OG, Twitter, v.v.) từ `MetaStatic`.
+- `<!--ssr-outlet-->` — chuỗi HTML đã được render của ứng dụng. Thường nằm bên trong `<div id="app">`.
+- `<!--ssr-teleports-->` — nội dung từ Vue Teleports.
+- `<!--ssr-scriptsJson-->` — **Nhãn cực kỳ quan trọng**. Chứa JSON với dữ liệu hydrat hóa (`ServerStorage`, bộ nhớ đệm API). Phải được đặt trước thẻ đóng `</body>`.
+Ví dụ `main.html`:
+```html
+<!DOCTYPE html>
+<html lang="<!--ssr-lang-->">
+<head>
+    <meta charset="UTF-8">
+    <!--ssr-meta-->
+    <title><!--ssr-title--></title>
+</head>
+<body>
+    <div id="app"><!--ssr-outlet--></div>
+    <!--ssr-teleports-->
+    <!--ssr-scriptsJson-->
+    <script type="module" src="/src/entry-client.ts"></script>
+</body>
+</html>
+```
+> Nếu không có nhãn `<!--ssr-scriptsJson-->`, dữ liệu nhận được trên server sẽ không được chuyển sang client, dẫn đến lỗi hydrat hóa và các yêu cầu API bị lặp lại.

package/src/media/functional/nitro-basic/functions/getInject.en.mdx DELETED Viewed

@@ -1,27 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks'
-<Meta title='@dxtmisha/en/nitro-basic/Functions/getInject - Get Injected Value'/>
-# `getInject`
-A utility function that safely reads an injected value by name from the current Vue component instance. If there is no active component instance or the value is not provided, it returns `undefined`.
-**Parameters:**
-- `name: string` — The injection key name.
-**Returns:**
-`T | undefined` — The injected value if it exists, otherwise `undefined`.
-```typescript
-import { provide } from 'vue'
-import { getInject } from '@dxtmisha/nitro-basic'
-provide('theme', 'dark')
-// Returns 'dark'
-const theme = getInject<string>('theme')
-// Returns undefined when the key is missing
-const language = getInject<string>('language')
-```

package/src/media/functional/nitro-basic/functions/getInject.ru.mdx DELETED Viewed

@@ -1,27 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks'
-<Meta title='@dxtmisha/ru/nitro-basic/Functions/getInject - Получение внедренного значения'/>
-# `getInject`
-Утилитарная функция, которая безопасно получает внедренное значение по имени из текущего экземпляра Vue-компонента. Если активного экземпляра компонента нет или значение не было предоставлено, функция возвращает `undefined`.
-**Параметры:**
-- `name: string` — Имя ключа внедрения.
-**Возвращает:**
-`T | undefined` — Внедренное значение, если оно существует, иначе `undefined`.
-```typescript
-import { provide } from 'vue'
-import { getInject } from '@dxtmisha/nitro-basic'
-provide('theme', 'dark')
-// Возвращает 'dark'
-const theme = getInject<string>('theme')
-// Возвращает undefined, если ключ отсутствует
-const language = getInject<string>('language')
-```

package/src/media/functional/nitro-basic/functions/getInject.vi.mdx DELETED Viewed

@@ -1,20 +0,0 @@
-import { Meta } from '@storybook/addon-docs/blocks'
-<Meta title='@dxtmisha/vi/nitro-basic/Functions/getInject - Lấy giá trị được inject'/>
-# `getInject`
-Một hàm tiện ích dùng để lấy an toàn giá trị được inject theo tên từ instance Vue hiện tại. Nếu không có instance component đang hoạt động hoặc giá trị chưa được cung cấp, hàm sẽ trả về `undefined`.
-**Tham số:**
-- `name: string` — Tên của khóa inject.
-**Trả về:**
-`T | undefined` — Giá trị được inject nếu tồn tại, ngược lại trả về `undefined`.
-**Ví dụ sử dụng:**
-- Gọi `getInject<string>('theme')` trong `setup()` để lấy giá trị đã được `provide`.
-- Nếu key không tồn tại hoặc không có component instance hiện tại, kết quả sẽ là `undefined`.