@lcap/nasl-unified-frontend-generator

本项目是NASL->前端应用代码的转译器。目前支持将NASL翻译成为 React 技术栈的源代码。

推荐使用pnpm进行依赖管理。

项目架构

插件领域划分

NASL前端generator领域
- 子领域：基础设施领域
  - 项目布局插件 ProjectOrganizationPlugin
  - 代码翻译器生命周期钩子插件 LifeCycleHooksPlugin
  - 文件系统插件 FileSystemPlugin
- 子领域：NASL领域
  - IR构建插件 IRBuilderPlugin
  - 路由抽取插件 RoutesExtractionPlugin
  - 元信息插件 MetadataPlugin
- 子领域：JavaScript语言领域
  - JavaScript代码生成插件 JavaScriptCodegenPlugin
  - JSX代码生成插件 JSXCodegenPlugin
  - 代码格式化插件 CodeFormatPlugin
  - 子领域：前端应用领域
    - 应用入口插件 EntrypointPlugin
    - 微前端插件 MicroFrontendPlugin
    - 子领域：React框架领域
      - React组件库适配插件 ReactComponentLibHackPlugin
      - React插槽适配插件 ReactSlotPlugin
      - React路由插件 ReactRouterPlugin
      - React MobX状态管理插件 ReactStateManagerMobXPlugin
      - React 原生状态管理插件 ReactStateManagerVanillaPlugin
      - 子领域：React代码生成领域
        
        React预置组插件 ReactPresetPlugin
        
        React代码生成插件 ReactCodegenPlugin
    - 子领域：其他前端框架
      - ...

规则：

父领域不可以依赖子领域的插件。一个领域内的插件只能使用当前领域及其祖先领域的知识，不能对兄弟领域和子领域做出假定。
- 例如，JavaScript代码生成插件不应该假定它会被框架领域的插件调用而生成任何框架相关的代码；微前端插件不应该假定它会被React框架调用。
由子领域插件向父领域提供知识。

开发

源代码位于packages/nasl-generator。

首次开发需要安装依赖并执行构建：

pnpm i
pnpm run --filter @lcap/nasl build
pnpm run --filter @lcap/nasl-unified-frontend-generator build

启动开发服务器(playground)，它用于本地快速调试NASL的翻译，命令如下：

pnpm dev

它会读取packages/nasl-generator/playground/fixtures/src.json作为NASL翻译。在翻译完成之后，会调用HTTP请求，将产物写入packages/nasl-react-server/out。

注意⚠️：为了确保写入正确，请先启动nasl-react-server。

更新Fixtures

packages/nasl-generator下，执行如下命令以更新playground/fixtures/src.json。

sh update-fixture.sh

这个脚本会调用batchQuery接口，将NASL树的JSON表示下载到本地。
如果更新失败，可能是cookie失效。请更新batchQuery.sh中的cURL部分。

nasl-react-server

位于packages/nasl-react-server。

作用：

提供接口供nasl-generator的playground调用，将翻译产物写入本地out文件夹。
将template（用以存储react的基本模板，包含rspack配置、package.json等等）文件夹复制到out文件夹，以提供产物执行的基本框架。这是因为nasl-generator的翻译产物并不会包括这些内容。

开发

首次开发请安装依赖：

pnpm i

执行如下命令启动开发服务器：

pnpm dev

每次启动开发服务器，都会

删除template文件夹中的node_modules
删除out文件夹
将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联调

全局安装yalc。

yalc是用于npm包本地开发的一个工具。可以在本地通过文件系统软链接形成一个registry，开发中的包可以发布到这个registry中，也可以从这个registry安装。一次发布(yalc publish --push)之后，所有从registry安装的开发中的包都会更新。

pnpm add -g yalc

在lcap-template项目下的packages/basic目录下，执行如下命令。

这会启动开发服务器（它会自动watch @lcap/basic-template的源码变化，编译，并将改动推送到本地yalc registry：

pnpm i
pnpm dev

在packages/nasl-react-server/template下，正常安装依赖即可。定义在packages/nasl-react-server/template/package.json里的postyalc hook会自动执行pnpm i命令，安装依赖。之后，在修改@lcap/basic-template源码之后，就会把改动自动同步到所有从本地yalc registry安装@lcap/basic-template的地方了。