npm - @dxtmisha/wiki - Versions diffs - 0.39.8 → 0.57.0 - Mend

@dxtmisha/wiki 0.39.8 → 0.57.0

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

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

@@ -0,0 +1,133 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+<Meta title='@dxtmisha/en/nitro-basic/# Project Setup'/>
+# Project Setup
+The `@dxtmisha/nitro-basic` library is designed to work in conjunction with Nitro and Vue 3. It ensures a smooth transition between server-side and client-side rendering. Below is a step-by-step guide for integrating the library into your project.
+## 1. Install Dependencies
+Install the necessary packages. In addition to the library itself, you will need Vue 3 and Vue Router:
+```bash
+npm install @dxtmisha/nitro-basic vue vue-router
+```
+## 2. Nitro Plugin Initialization
+For basic server environment setup (e.g., API caching), you need to register a Nitro plugin.
+Create the `server/plugins/ui.ts` file:
+```typescript
+import { definePlugin } from 'nitro'
+import { initPluginBasic } from '@dxtmisha/nitro-basic/plugin'
+export default definePlugin((nitroApp) => {
+  initPluginBasic(nitroApp)
+})
+```
+## 3. Create Application Factory (main.ts)
+Create a shared file for Vue application initialization that will be used on both server and 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. Configure Client Entry Point
+On the client, you need to prepare the identifier generator and mount the application.
+```typescript
+// src/entry-client.ts
+import { uiBootstrapClient, uiCreateClientApp } from '@dxtmisha/nitro-basic'
+import { createApp } from './main'
+const { app, router, options } = createApp()
+// ID initialization for hydration
+uiBootstrapClient()
+// Mount the application
+uiCreateClientApp(app, '#app', router, options)
+```
+## 5. Configure Server Entry Point
+The server entry point is responsible for initializing storages, headers, and HTML rendering.
+```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
+// Global server initialization
+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 Template
+For SSR to work correctly, the library uses a placeholder system in the HTML template. The `uiCreateServerApp` function automatically replaces them with up-to-date data.
+**Available markers:**
+- `<!--ssr-lang-->` — user language code (e.g., `en`). Used in `<html lang="...">`.
+- `<!--ssr-title-->` — page title from `MetaStatic`. Injected into `<title>`.
+- `<!--ssr-meta-->` — block of meta tags (OG, Twitter, etc.) from `MetaStatic`.
+- `<!--ssr-outlet-->` — rendered HTML of your application. Usually inside `<div id="app">`.
+- `<!--ssr-teleports-->` — content from Vue Teleports.
+- `<!--ssr-scriptsJson-->` — **Critically important marker**. Contains JSON with hydration data (`ServerStorage`, API cache). Must be placed before the closing `</body>`.
+Example `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>
+```
+> Without the `<!--ssr-scriptsJson-->` marker, data received on the server will not be transferred to the client, leading to hydration errors and redundant API requests.

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.