@file-viewer/vite-plugin 2.1.2 → 2.1.4

package/README.en.md

@@ -2,18 +2,35 @@
 
 Vite plugin for Flyfish File Viewer on-demand renderer assembly. It can auto-discover installed `@file-viewer/preset-*` packages and inject them into the page, so Vue, React, Svelte, jQuery, and Vanilla JS components receive matching preview capability without application code passing `renderers` manually. It can also generate `virtual:file-viewer-renderers` from declared formats, import only matching renderer packages, and provide renderer-oriented chunk planning plus offline worker/WASM/font asset copying.
 
-## Install
+## Fastest Start
+
+The fastest path is a standard component package, one preset, and one Vite plugin registration. The plugin auto-discovers installed `@file-viewer/preset-*` packages, so application code does not hand-write renderer imports and the plugin does not need `preset:'office'`. Installing the npm package alone does not make Vite run the plugin; register it once in `vite.config.ts`:
 
 ```bash
-pnpm add @file-viewer/vue3 @file-viewer/vite-plugin @file-viewer/renderer-pdf
+pnpm add @file-viewer/vue3 @file-viewer/preset-office
+pnpm add -D @file-viewer/vite-plugin
+```
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      copyAssets: true
+    })
+  ]
+})
 ```
 
-Install additional renderer packages when you need more formats, such as `@file-viewer/renderer-word`, `@file-viewer/renderer-ofd`, `@file-viewer/renderer-presentation`, `@file-viewer/renderer-cad`, `@file-viewer/renderer-drawing`, `@file-viewer/renderer-3d`, `@file-viewer/renderer-data`, `@file-viewer/renderer-eda`, `@file-viewer/renderer-typst`, `@file-viewer/renderer-archive`, or `@file-viewer/renderer-text`.
+Components keep `autoRenderers:true` by default, so `@file-viewer/vue3`, `@file-viewer/react`, `@file-viewer/web`, `@file-viewer/svelte`, `@file-viewer/jquery`, `@file-viewer/vue2.7`, and `@file-viewer/vue2.6` automatically consume the injected preset / renderer registry.
 
-When you want one package for a common product shape, install a preset:
+Heavy users that want the fastest full-capability setup can install the full preset and keep the same Vite config:
 
 ```bash
-pnpm add @file-viewer/vue3 @file-viewer/vite-plugin @file-viewer/preset-office
+pnpm add @file-viewer/vue3 @file-viewer/preset-all
+pnpm add -D @file-viewer/vite-plugin
 ```
 
 Available presets:
@@ -23,8 +40,20 @@ Available presets:
 - `@file-viewer/preset-engineering`: CAD, 3D, drawing, XMind, Geo, Typst, Archive, Data, and EDA.
 - `@file-viewer/preset-all`: the complete official demo format matrix.
 
+Install individual renderer packages only for strict cuts, such as `@file-viewer/renderer-pdf`, `@file-viewer/renderer-word`, `@file-viewer/renderer-ofd`, `@file-viewer/renderer-presentation`, `@file-viewer/renderer-cad`, `@file-viewer/renderer-drawing`, `@file-viewer/renderer-3d`, `@file-viewer/renderer-data`, `@file-viewer/renderer-eda`, `@file-viewer/renderer-typst`, `@file-viewer/renderer-archive`, or `@file-viewer/renderer-text`, then use `formats` to generate exact imports.
+
 ## vite.config.ts
 
+Prefer preset auto assembly for normal products. With no explicit `preset` option, or only `copyAssets:true`, the plugin auto-discovers installed `@file-viewer/preset-*` packages:
+
+```ts
+fileViewerRenderers({
+  copyAssets: true
+})
+```
+
+Use customization options only when you need source scanning, single-format cuts, or manual registry control:
+
 ```ts
 import { defineConfig } from 'vite'
 import { fileViewerRenderers } from '@file-viewer/vite-plugin'
@@ -41,15 +70,6 @@ export default defineConfig({
 })
 ```
 
-Or use one preset package:
-
-```ts
-fileViewerRenderers({
-  preset: 'office',
-  copyAssets: true
-})
-```
-
 `inject` is enabled by default. The plugin injects `virtual:file-viewer-renderers` into Vite HTML entrypoints, preset imports register themselves in core, and framework components consume them through `autoRenderers`.
 
 ```ts
@@ -59,11 +79,25 @@ const options = {
 }
 ```
 
+### Customization Options
+
+| Option | Description |
+| --- | --- |
+| `copyAssets` | `true` or `{ publicDir, outDir, mode }`; copies matched renderer Worker, WASM, font, and vendor assets |
+| `preset` | `'auto' | 'lite' | 'office' | 'engineering' | 'all'`; with no explicit formats, installed presets are discovered automatically |
+| `autoPresets` | `true` or a preset list; useful with `scan:true` when installed presets should stay active |
+| `formats` | File extensions or format tokens, for example `['pdf', 'docx', 'dwg']` |
+| `renderers` | Renderer ids, for example `['pdf', 'word', 'cad']` |
+| `scan` | `true` or `{ roots, extensions, maxFileSize }`; scans source hints and merges formats |
+| `inject` | Defaults to `true`; set `false` to import `virtual:file-viewer-renderers` manually |
+| `chunkStrategy` | `'renderer' | 'none'`; controls renderer-level chunk grouping |
+| `missingRenderer` | `'error' | 'warn' | 'ignore'`; controls notices for planned renderer mappings |
+
 For strict registry control, disable injection and pass the virtual module explicitly:
 
 ```ts
 fileViewerRenderers({
-  preset: 'office',
+  formats: ['pdf'],
   inject: false,
   copyAssets: true
 })
@@ -78,7 +112,17 @@ const options = {
 }
 ```
 
-You can also use `preset: 'auto'` to discover installed preset packages. When `preset-all` is installed, it wins to avoid importing narrower presets twice.
+You can also use `preset: 'auto'` to discover installed preset packages. When `preset-all` is installed, it wins to avoid importing narrower presets twice. Note: when `scan:true` is enabled, use `preset:'auto'` or `autoPresets:true` explicitly; otherwise the plugin treats source hints as the explicit renderer selection and skips zero-config preset discovery.
+
+```ts
+fileViewerRenderers({
+  preset: 'auto',
+  scan: true,
+  formats: ['pdf'],
+  copyAssets: true,
+  chunkStrategy: 'renderer'
+})
+```
 
 `scan: true` inspects common source folders for lightweight hints and merges them with `formats`:
 

package/README.md

@@ -2,18 +2,35 @@
 
 Flyfish File Viewer 的 Vite 按需 renderer 自动装配插件。它可以自动发现已安装的 `@file-viewer/preset-*` 包并注入到页面，让 Vue、React、Svelte、jQuery 和 Vanilla JS 组件无需手动传 `renderers` 就获得对应预览能力；也可以根据业务声明的文件格式生成 `virtual:file-viewer-renderers`，只 import 命中的 renderer 包，并提供 chunk 分组和离线 worker/WASM/字体资源复制能力。
 
-## 安装
+## 最快开始
+
+最快接入路径是“标准组件包 + 一个 preset + 注册一次 Vite 插件”。插件会自动发现当前项目已安装的 `@file-viewer/preset-*`，无需手写 renderer import，也无需给插件显式写 `preset:'office'`。注意：只安装 npm 包不会让 Vite 自动运行插件，仍需要在 `vite.config.ts` 中注册一次：
 
 ```bash
-pnpm add @file-viewer/vue3 @file-viewer/vite-plugin @file-viewer/renderer-pdf
+pnpm add @file-viewer/vue3 @file-viewer/preset-office
+pnpm add -D @file-viewer/vite-plugin
+```
+
+```ts
+import { defineConfig } from 'vite'
+import { fileViewerRenderers } from '@file-viewer/vite-plugin'
+
+export default defineConfig({
+  plugins: [
+    fileViewerRenderers({
+      copyAssets: true
+    })
+  ]
+})
 ```
 
-需要更多格式时安装对应 renderer 包，例如 `@file-viewer/renderer-word`、`@file-viewer/renderer-ofd`、`@file-viewer/renderer-presentation`、`@file-viewer/renderer-cad`、`@file-viewer/renderer-drawing`、`@file-viewer/renderer-3d`、`@file-viewer/renderer-data`、`@file-viewer/renderer-eda`、`@file-viewer/renderer-typst`、`@file-viewer/renderer-archive`、`@file-viewer/renderer-text`。
+组件默认 `autoRenderers:true`，会读取 Vite 插件注入的 preset / renderer registry。常规业务代码只要使用 `@file-viewer/vue3`、`@file-viewer/react`、`@file-viewer/web`、`@file-viewer/svelte`、`@file-viewer/jquery`、`@file-viewer/vue2.7` 或 `@file-viewer/vue2.6` 即可获得对应能力。
 
-如果你希望用一个包完成常见场景装配，可以安装 preset：
+重度用户需要最快拥有全部预览能力时，直接安装全量 preset，Vite 配置保持不变：
 
 ```bash
-pnpm add @file-viewer/vue3 @file-viewer/vite-plugin @file-viewer/preset-office
+pnpm add @file-viewer/vue3 @file-viewer/preset-all
+pnpm add -D @file-viewer/vite-plugin
 ```
 
 可选 preset：
@@ -23,8 +40,20 @@ pnpm add @file-viewer/vue3 @file-viewer/vite-plugin @file-viewer/preset-office
 - `@file-viewer/preset-engineering`: CAD、3D、绘图、XMind、Geo、Typst、Archive、Data、EDA。
 - `@file-viewer/preset-all`: 官方 demo 完整格式矩阵。
 
+如果只需要极少数格式，也可以安装对应 renderer 包，例如 `@file-viewer/renderer-pdf`、`@file-viewer/renderer-word`、`@file-viewer/renderer-ofd`、`@file-viewer/renderer-presentation`、`@file-viewer/renderer-cad`、`@file-viewer/renderer-drawing`、`@file-viewer/renderer-3d`、`@file-viewer/renderer-data`、`@file-viewer/renderer-eda`、`@file-viewer/renderer-typst`、`@file-viewer/renderer-archive`、`@file-viewer/renderer-text`，再通过 `formats` 做精确裁剪。
+
 ## vite.config.ts
 
+推荐默认使用 preset 自动装配。无参或只传 `copyAssets:true` 时，插件会自动发现已安装的 `@file-viewer/preset-*`，无需写 `preset:'office'`：
+
+```ts
+fileViewerRenderers({
+  copyAssets: true
+})
+```
+
+只有在需要源码扫描、单格式裁剪、或手动 registry 管理时，再使用自定义能力：
+
 ```ts
 import { defineConfig } from 'vite'
 import { fileViewerRenderers } from '@file-viewer/vite-plugin'
@@ -41,15 +70,6 @@ export default defineConfig({
 })
 ```
 
-或者使用 preset 一包装配：
-
-```ts
-fileViewerRenderers({
-  preset: 'office',
-  copyAssets: true
-})
-```
-
 `inject` 默认开启，插件会把 `virtual:file-viewer-renderers` 注入 Vite HTML 入口，preset 导入后会自动注册到 core。常规业务只需要安装组件包和对应 preset，组件会通过 `autoRenderers` 默认读取这些能力。
 
 ```ts
@@ -59,11 +79,25 @@ const options = {
 }
 ```
 
+### 可定制能力
+
+| 选项 | 说明 |
+| --- | --- |
+| `copyAssets` | `true` 或 `{ publicDir, outDir, mode }`，复制匹配 renderer 的 Worker、WASM、字体和 vendor 资源 |
+| `preset` | `'auto' | 'lite' | 'office' | 'engineering' | 'all'`；默认无显式格式时自动发现已安装 preset |
+| `autoPresets` | `true` 或 preset 列表；常用于 `scan:true` 时继续自动激活已安装 preset |
+| `formats` | 文件扩展名或格式 token，例如 `['pdf', 'docx', 'dwg']` |
+| `renderers` | renderer id，例如 `['pdf', 'word', 'cad']` |
+| `scan` | `true` 或 `{ roots, extensions, maxFileSize }`，扫描源码 hint 并合并格式 |
+| `inject` | 默认 `true`；设为 `false` 后手动导入 `virtual:file-viewer-renderers` |
+| `chunkStrategy` | `'renderer' | 'none'`，控制是否注入 renderer 级 chunk 分组 |
+| `missingRenderer` | `'error' | 'warn' | 'ignore'`，控制尚未提取的 renderer 映射提示方式 |
+
 如果你需要严格控制 registry，可以关闭注入并手动传入：
 
 ```ts
 fileViewerRenderers({
-  preset: 'office',
+  formats: ['pdf'],
   inject: false,
   copyAssets: true
 })
@@ -78,7 +112,17 @@ const options = {
 }
 ```
 
-也可以使用 `preset: 'auto'` 发现项目中已安装的 preset 包；当 `preset-all` 存在时会优先使用它，避免重复导入其它 preset。
+也可以使用 `preset: 'auto'` 发现项目中已安装的 preset 包；当 `preset-all` 存在时会优先使用它，避免重复导入其它 preset。注意：如果同时开启 `scan:true`，请显式使用 `preset:'auto'` 或 `autoPresets:true`，否则插件会以源码 hint 为准，不再做“无配置 preset 自动发现”。
+
+```ts
+fileViewerRenderers({
+  preset: 'auto',
+  scan: true,
+  formats: ['pdf'],
+  copyAssets: true,
+  chunkStrategy: 'renderer'
+})
+```
 
 `scan: true` 会扫描常见源码目录里的轻量 hint，并把它们合并到 `formats`：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@file-viewer/vite-plugin",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "private": false,
   "type": "module",
   "description": "Vite plugin for Flyfish File Viewer on-demand renderer assembly, chunk planning, and offline asset deployment.",