@michaeltangseng/schemaai 0.0.1

package/docs/publish-to-npm.md

@@ -0,0 +1,148 @@
+## schemaAI 发布到 npm 的步骤
+
+本指南用于在本地构建完成后，将 `schemaAI` 包发布到 npm Registry。  
+假设包名为：`@michaeltangseng/schemaai`。
+
+> ⚠️ 建议在发布前先确认：包名未被他人占用、版本号符合预期、`dist/` 已成功生成。
+
+---
+
+## 1. 发布前检查清单
+
+在目录 `Others/utils-lib/npm-package` 下：
+
+- **确认构建成功**
+  ```bash
+  pnpm run build   # 或 npm run build
+  ```
+  - 预期：无 TypeScript 报错，生成 `dist/` 目录。
+
+- **检查关键文件**
+  - `package.json`：
+    - `name`: `@michaeltangseng/schemaai`
+    - `version`: `0.0.1`（首次发布建议用 0.x，后续升级按 semver 调整）
+    - `main`, `module`, `types` 指向 `dist` 下文件。
+    - `author`, `license`, `description`, `keywords` 确认无误。
+  - `dist/`：
+    - 至少包含构建出的入口文件和类型声明（如 `index.js` / `index.d.ts` 等）。
+
+- **确认忽略配置**
+  - 如果后续添加了 `.npmignore` 或通过 `package.json.files` 控制发布内容，需确保：
+    - `dist/` 被包含；
+    - 不必要的测试/配置文件可以排除。
+
+---
+
+## 2. npm 账号与登录
+
+在终端任意位置执行：
+
+```bash
+npm login
+```
+
+按提示输入：
+
+- npm 用户名
+- 密码
+- 邮箱验证码（如开启了 2FA，则按 npm 的 2FA 方式完成验证）
+
+> 只需登录一次，后续在本机同一用户下发布同一 scope 的包时可复用登录状态。
+
+---
+
+## 3. 确认包名是否已被占用（可选但推荐）
+
+在浏览器或终端中检查：
+
+- 浏览器访问：`https://www.npmjs.com/package/@michaeltangseng/schemaai`
+  - 如果返回 404，说明还未被占用，可以发布。
+
+---
+
+## 4. 实际发布命令
+
+在 `Others/utils-lib/npm-package` 目录下执行：
+
+```bash
+npm publish --access public
+```
+
+说明：
+
+- 若 `name` 使用了 scope（如 `@michaeltangseng/schemaai`），首次发布时必须显式加上 `--access public`。
+- 发布过程会自动触发：
+  - `prepare` 脚本（`npm run build`），确保发布的是最新构建产物。
+
+> 若发布过程中出现「2FA 相关提示」，按 npm 帐号配置完成额外验证码输入即可。
+
+---
+
+## 5. 发布成功后的验证
+
+### 5.1 在 npm 官网确认
+
+- 打开浏览器访问：  
+  `https://www.npmjs.com/package/@michaeltangseng/schemaai`
+- 检查：
+  - README/描述是否正确（后续可在包根目录添加 `README.md` 并重新发布版本）。
+  - 版本号是否为刚发布的版本。
+
+### 5.2 在独立项目中安装验证
+
+新建或在已有前端项目中（不在当前 monorepo 内）执行：
+
+```bash
+npm install @michaeltangseng/schemaai
+# 或
+pnpm add @michaeltangseng/schemaai
+```
+
+然后在代码中使用：
+
+```ts
+import { schemaAIRenderer as SchemaAIRenderer } from '@michaeltangseng/schemaai';
+
+const demoSchema = {
+  id: 'root',
+  type: 'Container',
+  props: { title: 'Hello schemaAI from npm' },
+  style: { padding: '16px' },
+  children: []
+};
+
+export function App() {
+  return <SchemaAIRenderer schema={demoSchema} />;
+}
+```
+
+如果页面能正常渲染出容器和标题，说明 npm 包发布与使用流程已经闭环。
+
+---
+
+## 6. 版本升级与变更建议
+
+- **版本号策略**：
+  - 早期快速迭代阶段使用 `0.x.y`，不保证完全稳定。
+  - 当 Public API（见 `docs/public-api.md`）相对稳定后，再发布 `1.0.0`。
+- **每次发版前**：
+  1. 更新 `package.json` 中的 `version`，遵循 semver（`patch`/`minor`/`major`）。
+  2. 更新相关文档（如 `CHANGELOG`、`public-api.md`、`migrate-plan.md` 若涉及重大变更）。
+  3. `pnpm run build` 确认通过。
+  4. 执行 `npm publish --access public`。
+
+---
+
+## 7. 常见问题（简要）
+
+- **Q：本地能 build，通过 `npm link` 也正常，为什么发布后安装报错？**  
+  A：通常与发布内容不一致有关（如 `dist/` 未包含在 npm 包中，或入口字段 `main/module/types` 指向了不存在的文件）。  
+  建议发布前使用 `npm pack` 检查打包结果：
+  ```bash
+  npm pack
+  ```
+  解压生成的 `.tgz`，检查其中包含的文件结构。
+
+- **Q：想废弃某个版本怎么办？**  
+  A：可以在 npm 官网将该版本标记为 deprecated，并在说明中提示用户升级到新的版本。
+

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@michaeltangseng/schemaai",
+  "version": "0.0.1",
+  "description": "schemaAI - React schema-driven low-code engine core (extracted from react-low-code-engine).",
+  "private": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0"
+  },
+  "keywords": [
+    "schemaai",
+    "low-code",
+    "react",
+    "schema",
+    "renderer"
+  ],
+  "author": "michaeltangseng",
+  "license": "MIT"
+}
+