@lcap/nasl-unified-frontend-generator 0.0.0-beta.1

package/README.md

@@ -0,0 +1,104 @@
+# @lcap/nasl-unified-generator
+
+![文档覆盖](./coverage.svg)
+
+本项目是NASL->前端应用代码的转译器。目前支持将NASL翻译成为 React 技术栈的源代码。
+
+推荐使用pnpm进行依赖管理。
+
+## 项目架构
+
+TBA
+
+### 开发
+
+源代码位于`packages/nasl-generator`。
+
+首次开发需要安装依赖。
+
+```
+pnpm i
+```
+
+启动开发服务器(playground)，它用于本地快速调试NASL的翻译，命令如下：
+
+```
+pnpm dev
+```
+
+它会读取`packages/nasl-generator/playground/fixtures/src.json`作为NASL翻译。在翻译完成之后，会调用HTTP请求，将产物写入`packages/nasl-react-server/out`。
+
+
+#### 更新Fixtures
+
+`packages/nasl-generator`下，执行如下命令以更新`playground/fixtures/src.json`。
+
+```
+sh update-fixture.sh
+```
+
+1. 这个脚本会调用batchQuery接口，将NASL树的JSON表示下载到本地。
+1. 如果更新失败，可能是cookie失效。请更新`batchQuery.sh`中的cURL部分。
+
+### nasl-react-server
+
+位于`packages/nasl-react-server`。
+
+作用：
+
+1. 提供接口供`nasl-generator`的`playground`调用，将翻译产物写入本地`out`文件夹。
+1. 将`template`（用以存储react的基本模板，包含rspack配置、package.json等等）文件夹复制到`out`文件夹，以提供产物执行的基本框架。这是因为`nasl-generator`的翻译产物并不会包括这些内容。
+
+#### 开发
+
+首次开发请安装依赖：
+
+```
+pnpm i
+```
+
+执行如下命令启动开发服务器：
+
+```
+pnpm dev
+```
+
+每次启动开发服务器，都会
+1. 删除`template`文件夹中的`node_modules`
+1. 删除`out`文件夹
+2. 将`template`文件夹复制为`out`文件夹
+
+> ⚠注意️：`out`文件夹下的文件都是临时的，会被`nasl-generator`覆盖。每次如果想要改动持久保持，请修改`template`文件夹。
+
+#### 产物启动
+
+在启动`nasl-generator`的开发服务器进行翻译之后，翻译的产物存在于`out`目录下。这个翻译产物已经执行过`pnpm i`，因此可以直接启动：
+
+```
+pnpm dev
+```
+
+如果出现`@lcap/basic-template`未安装的错误，可能是因为目前正在从yalc引用`@lcap/basic-template`。请参考`@lcap/basic-template`联调指南一章。
+
+## 指南
+
+### 与@lcap/basic-template联调
+
+1. 全局安装`yalc`。
+
+yalc是用于npm包本地开发的一个工具。可以在本地通过文件系统软链接形成一个registry，开发中的包可以发布到这个registry中，也可以从这个registry安装。一次发布(yalc publish --push)之后，所有从registry安装的开发中的包都会更新。
+
+```
+pnpm add -g yalc
+```
+
+2. 在[lcap-template](https://github.com/vusion-templates/lcap-template)项目下的`packages/basic`目录下，执行如下命令。
+
+这会启动开发服务器（它会自动watch @lcap/basic-template的源码变化，编译，并将改动推送到本地yalc registry：
+
+```
+pnpm i
+pnpm dev
+```
+
+3. 在`packages/nasl-react-server/template`下，正常安装依赖即可。定义在`packages/nasl-react-server/template/package.json`里的`postyalc` hook会自动执行`pnpm i`命令，安装依赖。之后，在修改`@lcap/basic-template`源码之后，就会把改动自动同步到所有从本地yalc registry安装`@lcap/basic-template`的地方了。