file-viewer/WRAPPER_ECOSYSTEM.md

File Viewer Component Ecosystem

This document records the public component repository plan. @file-viewer/core is the framework-neutral TypeScript foundation; every framework package builds its own native component experience on top of the same core contracts. Component packages must not depend on another framework implementation, and all shared low-level rendering contracts stay under the single core package.

Public Component Packages

Framework	npm package	GitHub	Gitee	Source directory
Vue 3	@file-viewer/vue3	flyfish-dev/file-viewer-vue3	flyfish-dev/file-viewer-vue3	packages/components/vue3
Vue 2.7	@file-viewer/vue2.7	flyfish-dev/file-viewer-vue2.7	flyfish-dev/file-viewer-vue2.7	packages/components/vue2.7
Vue 2.6	@file-viewer/vue2.6	flyfish-dev/file-viewer-vue2.6	flyfish-dev/file-viewer-vue2.6	packages/components/vue2.6
React 18/19	@file-viewer/react	flyfish-dev/file-viewer-react	flyfish-dev/file-viewer-react	packages/components/react
React 16.8/17	@file-viewer/react-legacy	flyfish-dev/file-viewer-react-legacy	flyfish-dev/file-viewer-react-legacy	packages/components/react-legacy
Pure Web	@file-viewer/web	flyfish-dev/file-viewer-web	flyfish-dev/file-viewer-web	packages/components/web
jQuery	@file-viewer/jquery	flyfish-dev/file-viewer-jquery	flyfish-dev/file-viewer-jquery	packages/components/jquery
Svelte	@file-viewer/svelte	flyfish-dev/file-viewer-svelte	flyfish-dev/file-viewer-svelte	packages/components/svelte

The canonical machine-readable matrix is ecosystem/wrappers.json.

Standalone Repo Export

Generate local standalone repository folders for review or push:

pnpm components:export

The export command first refreshes all component README files from ecosystem/wrappers.json and the core format definitions, then writes to .release/wrapper-repos/<repository>. Each folder contains:

• package source and package metadata
• Chinese and English README
• root LICENSE
• a standalone .gitignore
• wrapper-repo-manifest.json with source commit and repository metadata

Workspace dependency specifiers such as workspace:^2.0.1 are rewritten to normal npm ranges before export, so the folders are ready to initialize as standalone public repositories.

Refresh README files without exporting standalone repositories:

pnpm components:readme

The same command also refreshes the generated public ecosystem block in the root README.md and README.en.md. Because the open-source main repository copies those files, the repository homepage keeps the standard npm packages, GitHub component repositories, Gitee mirrors, core source visibility note and current format-count summary in sync with ecosystem/wrappers.json.

Verify source component packages and exported standalone repositories:

pnpm components:verify

The verifier checks package names, npm entry metadata (main, module, types, exports), README language pairs, generated ecosystem/format blocks, official documentation and demo links, Apache-2.0 attribution guidance, standalone manifests, GitHub/Gitee metadata, and the absence of build output, workspace dependencies or private workspace folders in exported repositories.

Prepare the exported folders as standalone Git repositories without pushing:

pnpm components:publish:dry-run

Push every exported component repository to its GitHub origin and Gitee gitee remotes:

pnpm components:publish

components:publish runs the export and verification pipeline first, then initializes or updates each folder in .release/wrapper-repos, configures remotes from ecosystem/wrappers.json, commits the current export with chore: sync wrapper release, and pushes the selected branch. Use node scripts/publish-wrapper-repos.mjs --id=react --push or --package=@file-viewer/react --push when only one component package needs to be refreshed.

From the private aggregate workspace, Gitee mirrors can be bootstrapped from the same manifest once an organization token has repository creation permission:

FILE_VIEWER_GITEE_TOKEN=<token> pnpm components:gitee:create
FILE_VIEWER_GITEE_TOKEN=<token> pnpm components:gitee:publish
pnpm verify:wrapper-public-remotes --host=gitee

components:gitee:create creates the core and standard component repositories under flyfish-dev when missing. It does not print the token and supports --dry-run, --id=<wrapper> and --package=<name> for targeted checks. These commands are maintainer automation in the private aggregate workspace; the open-source main repository keeps the resulting source packages and public metadata.

npm Ecosystem Release

Use the ecosystem release helper to keep core, standard wrappers and compatibility packages on the same version:

pnpm release:ecosystem:list
pnpm release:ecosystem:pack
pnpm release:ecosystem:publish:dry-run
pnpm release:ecosystem:publish

The helper currently covers 14 public npm targets:

• @file-viewer/core
• @file-viewer/vue3, @file-viewer/vue2.7, @file-viewer/vue2.6
• @file-viewer/react, @file-viewer/react-legacy
• @file-viewer/web, @file-viewer/jquery, @file-viewer/svelte
• @flyfish-group/file-viewer3, file-viewer3, @flyfish-group/file-viewer
• @flyfish-group/file-viewer-web, @flyfish-group/file-viewer-react

It verifies public publish settings, type declarations, package entry files, README language pairs and version alignment before packing or publishing. The compatibility packages remain synchronized for existing customers; new integrations should prefer the standard @file-viewer/* names.

Open-Source Main Sync

scripts/sync-public-main.mjs delegates npm tarball creation to the same ecosystem release helper, then reads the generated npm-release-manifest.json. During a full open-source main release it packs:

• the compiled core foundation tarball @file-viewer/core
• historical compatibility packages such as @flyfish-group/file-viewer3, @flyfish-group/file-viewer, @flyfish-group/file-viewer-web, and @flyfish-group/file-viewer-react
• every standard component package listed in the manifest

The unscoped file-viewer3 compatibility package remains part of the npm release flow, but the open-source main repository omits its duplicate tarball and records that policy in artifacts/release-manifest.json. The generated manifest records each package, whether its tarball is included, the GitHub repository, and the Gitee mirror for every public integration.