inkreachhub/inkreach-teable-cli
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(skill): plugin bundle pipeline v2 (IIFE/多资产/热更新) 文档入仓

Browse Source
This commit is contained in:
yeuimu
2026-10-14 00:20:56 +00:00
parent c9694511a1
commit a3fa01e25f
8 changed files with 338 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/inkreach-teable-plugin/SKILL.md
+26 -12
View File
@@ -23,18 +23,31 @@ rebuilding the host Next.js app. Plugins are IIFE bundles — they ship as plain
JS that executes in the host page and accesses host APIs through
`window.__TEABLE_HOST__`.
> **Contract**: A plugin = a webpack IIFE bundle (`dist/main.js` + optional
> `dist/styles.css`) + `plugin.json` manifest, uploaded to the host via
> `POST /api/plugin/:id/upload-bundle`. It runs in the same React tree as the host
> and has full access to the host's SDK, UI library, and OpenAPI helpers.
> **Contract**: A plugin = a webpack (or vite) IIFE bundle (`dist/main.js` +
> optional lazy chunks `*.chunk.js`, source maps `*.js.map`, `styles.css`) +
> a `plugin.json` manifest, uploaded to the host via
> `POST /api/plugin/:id/upload-bundle` (or `teable-plugin deploy`, which
> handles all assets). It runs in the same React tree as the host and has
> full access to the host's SDK, UI library, and OpenAPI helpers.
>
> **Dev loop**: `teable-plugin dev` (or `pnpm dev` in scaffolded projects)
> watch-builds and auto-uploads with a `devMode` manifest; the open host page
> remounts the plugin within ~4s without a page refresh. See
> `dynamic-plugins/dev-workflow.md`.
>
> **Full-page apps**: install at position `route` and the host serves the
> plugin on `/base/<baseId>/p/<pluginId>` (whole viewport, own router OK —
> HashRouter recommended).
>
> **Critical constraint**: no RUNTIME imports from `@teable/sdk`, `@teable/ui-lib`,
> `@teable/openapi` — webpack maps them to `window.__TEABLE_HOST__.*` externals, so a
> value import compiles to `undefined` at runtime. `import type { X } from '@teable/...'`
> IS fine (erased at compile time). `react`/`react-dom` may be imported ONLY when your
> webpack `externals` maps them to `window.__TEABLE_HOST__.React/ReactDOM` (see the
> batch-edit-pro webpack config). For everything else, read from the host global:
> `const { useFields } = window.__TEABLE_HOST__.SDK`. See
> `@teable/openapi` — a value import via monorepo aliases inlines the whole
> package source (via window-global externals it compiles to `undefined`).
> `import type { X } from '@teable/...'` IS fine (erased at compile time).
> `react`/`react-dom` may be imported when your webpack `externals` maps them
> to `window.__TEABLE_HOST__.React/ReactDOM` (see the plugin-showcase webpack
> config; `react/jsx-runtime` is intentionally bundled — element factories
> only, hooks stay on the host singleton). For everything else, read from the
> host global: `const { useFields } = window.__TEABLE_HOST__.SDK`. See
> `dynamic-plugins/troubleshooting.md` Pitfall 1 for details and symptoms.
## 0. Two efficiency rules (read first)
@@ -71,8 +84,9 @@ JS that executes in the host page and accesses host APIs through
| 3. SDK API | `dynamic-plugins/sdk-api.md` | when writing plugin logic — definePlugin, PluginContext, events, storage, useSelection, native form embedding (`NativeForm` Tier-1 injection / `NativeFormScope`+`useNativeForm` Tier-2 kit), NativeGrid |
| 3b. Native form quick answer | `dynamic-plugins/native-form.md` | **when the user ASKS whether/how to embed native field editors, custom form layout, or multi-step forms — read this FIRST and answer directly (consultative questions need no scaffold/build)** |
| 4. Deployment | `dynamic-plugins/deployment.md` | when uploading + enabling + authority matrix permissions |
| 5. Troubleshooting | `dynamic-plugins/troubleshooting.md` | before writing logic — common pitfalls (host globals, developer whitelist, AM, empty states) |
| Ref: batch-edit-pro | `plugins/batch-edit-pro/` | the canonical example — contextMenu plugin, full React + SDK |
| 5. Troubleshooting | `dynamic-plugins/troubleshooting.md` | before writing logic — common pitfalls (host globals, developer whitelist, AM, empty states, chunk-name flattening, terser banners) |
| Ref: plugin-showcase | `plugins/plugin-showcase/` | the v2 example — lazy chunks + source maps + Tailwind + HashRouter route app |
| Ref: batch-edit-pro | `plugins/batch-edit-pro/` | the classic example — single-file contextMenu plugin, full React + SDK |
## 3. Quick decision: which position?