1flowbase Web External npm

用于把浏览器兼容的外部 npm 依赖预构建为一个可部署到 1flowbase Nginx 静态目录的扩展包。生产环境不运行 Node.js，也不在线安装 npm 包。

当前样例

• dayjs：Browser ESM。
• zod：Browser ESM。
• tailwindcss：一个轻量 Browser ESM 标记模块和一份预编译 Shadow DOM CSS。

一个扩展包可以同时包含多个依赖，最终只上传一个 release/external-npm-pack.tar.gz。

本地运行

pnpm install --ignore-scripts
pnpm test
pnpm dev

pnpm dev 会先生成当前扩展包，再监听 127.0.0.1:4174：

http://127.0.0.1:4174/external-npm/manifest.json

1flowbase Web 开发服务器默认把 /external-npm/ 代理到该地址，也可以在 web/app/.env 中覆盖：

VITE_EXTERNAL_NPM_PROXY_TARGET=http://127.0.0.1:4174

低代码区块继续使用普通导入：

import dayjs from 'dayjs';
import { z } from 'zod';
import 'tailwindcss';

export default function Example() {
  const date = z.string().parse('2026-08-11');
  return (
    <div className="rounded-xl bg-sky-600 px-6 py-4 text-white shadow-lg">
      {dayjs(date).format('YYYY-MM-DD')}
    </div>
  );
}

添加或升级依赖

1. 在 package.json 中添加或调整精确版本。
2. 在 external-npm.config.mjs 中登记公开的包名与入口。
3. 运行 pnpm install --ignore-scripts && pnpm test && pnpm build。
4. 整体上传新的 release/external-npm-pack.tar.gz。

构建会自动生成 dist/manifest.json、带摘要文件名的资产和单个归档。dist/、release/、源码、node_modules/ 和历史版本不会一起提交或装进归档。

Tailwind 必须在构建期知道 class 名。当前样例从 src/tailwind-source.html 扫描 class；新增 class 后重新构建并整体替换扩展包。运行时动态拼接、未进入扫描输入的 class 不会自动产生 CSS。

Node builtin、native addon、lifecycle install scripts 和运行时公网依赖不在支持范围内。安装脚本通过仓库 .npmrc 默认禁用。

部署

停止 Web 容器，把归档内容整体解压到 1flowbase 的 docker/web/external-npm/，再启动 Web 容器：

docker compose stop web
rm -f docker/web/external-npm/manifest.json
rm -rf docker/web/external-npm/assets
tar -xzf external-npm-pack.tar.gz -C docker/web/external-npm/
docker compose up -d web

服务器目录只保存当前包。需要回退时，重新上传并解压运维侧保留的旧归档。

实现范围、验收标准和停止条件以 Issue #1 为唯一真值。