@_tc/template-core 0.3.0 → 0.3.1

package/.skills/tc-generator/SKILL.md

@@ -27,6 +27,7 @@ This workspace is the TemplateCore npm package repository (`@_tc/template-core`)
 3. Generate the smallest working slice first: config, entry, controller, router, model.
 4. Keep keys stable. Array merge and project overrides depend on `key`.
 5. Prefer CommonJS `.js` for generated consumer examples unless the existing consumer app already uses TypeScript.
+6. If the existing consumer app declares `"type": "module"`, do not generate `.js` backend convention files with `module.exports` under that scope. Use `.ts` convention files, or add a local `package.json` with `{ "type": "commonjs" }` under `app/`, `config/`, or `models/` before generating CommonJS `.js` files.
 
 ## TemplateCore Conventions
 

package/AGENT_README.md

@@ -124,6 +124,20 @@ models/**/*.(js|ts)               -> 内置 project service 读取的项目模
 ssr/apps/**/*.entry.(js|jsx|ts|tsx) -> SSR 页面入口，可选
 ```
 
+### 3.1 后端约定文件的模块格式
+
+`@_tc/template-core` 包本身提供 ESM/CJS 入口，使用方项目可以用 `import` 引入包。但 `config/`、`app/`、`models/` 里的后端约定文件由 loader 扫描真实文件路径后同步加载，当前按 `require()` 语义处理，并只扫描 `.js` / `.ts`。
+
+后端约定文件需要满足 CommonJS 加载语义：
+
+- 普通 CommonJS 项目可以使用 `.js` + `module.exports`。
+- TypeScript 项目可以使用 `.ts` + `export default`，loader 会把 `.ts` 按 CommonJS 方式转译后加载。
+- 如果业务项目声明了 `"type": "module"`，不要把 `.js` 后端约定文件写成原生 ESM 作为稳定用法，也不要在该作用域下使用 `.js` + `module.exports`。
+- `"type": "module"` 项目如需保留 `.js` 后端约定文件，请在 `app/`、`config/` 或 `models/` 下增加局部 `package.json`：`{ "type": "commonjs" }`。
+- `.mjs`、顶层 `await`、依赖原生 ESM 语义的后端约定文件当前不作为支持约定。
+
+推荐分层：启动脚本、构建脚本和前端代码可以使用 ESM；`config/`、`app/`、`models/` 里的后端约定文件保持 CommonJS 加载语义。
+
 常用后端类型：
 
 | 类型 | 使用场景 |

package/README.md

@@ -656,6 +656,20 @@ config/config.{env}.(js|ts)      -> app.config
 models/**/*.(js|ts)               -> 内置 project service 按需读取的项目模型配置
 ```
 
+### 后端约定文件的模块格式
+
+TemplateCore 包本身提供 ESM/CJS 入口，业务项目可以用 `import` 引入包。但上面这些后端约定文件是由 loader 扫描真实文件路径后同步加载的，当前按 `require()` 语义处理，并只扫描 `.js` / `.ts`。
+
+因此后端约定文件需要满足 CommonJS 加载语义：
+
+- 普通 CommonJS 项目可以使用 `.js` + `module.exports`。
+- TypeScript 项目可以使用 `.ts` + `export default`，loader 会把 `.ts` 按 CommonJS 方式转译后加载。
+- 如果业务项目声明了 `"type": "module"`，不要把 `.js` 后端约定文件写成原生 ESM 作为稳定用法，也不要在该作用域下使用 `.js` + `module.exports`。
+- `"type": "module"` 项目如需保留 `.js` 后端约定文件，请在 `app/`、`config/` 或 `models/` 下增加局部 `package.json`：`{ "type": "commonjs" }`。
+- `.mjs`、顶层 `await`、依赖原生 ESM 语义的后端约定文件当前不作为支持约定。
+
+推荐分层：启动脚本、构建脚本和前端代码可以使用 ESM；`config/`、`app/`、`models/` 里的后端约定文件保持 CommonJS 加载语义。
+
 内置扩展：
 
 - `app.extends.$fetch`：Node 侧基于 `fetch` 的 axios 风格请求实例，支持 `get/post/put/patch/delete` 和 `create(config)`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_tc/template-core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A full-stack TypeScript admin framework package powered by Koa, React, and Vite",
   "types": "./types/index.d.ts",
   "exports": {