San SSR
优质
小牛编辑
122浏览
2023-12-01
本仓库的 目的 是为 san 提供一个 SSR 代码框架和工具,以及内置了 JavaScript 的代码生成。
- English
- SSR 代码迁移:从 san 到 san-ssr
- Demo:demo/
安装
npm i san@latest san-ssr@latest
san-ssr 需要 san 提供的模板字符串解析和 TypeScript 类型,因此对 san 的版本有依赖。你需要安装对应版本的 san 和 san-ssr。 san-ssr 支持的 san 版本声明在 peerDependencies
里,因此只要能安装成功就能正确工作。一般的建议如下:
- 如果是新项目,建议使用
npm i san@latest san-ssr@latest
- 否则从 san-ssr 最新版本开始降主版本号找到能安装成功的版本。
更多讨论请参考:baidu/san/issues/441
使用
SanProject 类 提供了你会用到的所有接口:
- 输入是组件对象。
- 输出是一个 render 函数。该函数接受数据对象作为参数,返回 HTML 字符串。
const { SanProject } = require('san-ssr')
const app = require('src/component.js')
const project = new SanProject()
const render = project.compileToRenderer(app)
console.log(render({name: 'harttle'}))
详细请参考 API 文档:SanProject,或 /demo 下的示例项目。
其他目标平台
san-ssr 提供了 San 组件的静态分析,提供了项目文件集合和 San 组件树,以及二者的对应关系。 具体的代码生成抽象为 Compiler 接口,目前有 JS 和 PHP 两个实现,其中 san-ssr-target-js 内置在本仓库中:
CLI 参数 --target
参数用来选择目标代码,默认为 js
:
san-ssr --target js ./component.js > ssr.js
编程接口也可以通过 SanProject#compile()
的第二个参数来指定目标,第三个参数来指定传给 Compiler 实现的参数:
import { Target, SanProject } from 'san-ssr'
import { writeFileSync } from 'fs'
const project = new SanProject()
const targetCode = project.compile('src/component.ts', Target.PHP, { emitHeader: true })
writeFileSync('ssr.php', targetCode)
指定非 js
的目标时,san-ssr 会从 CWD 开始寻找 san-ssr-target-${target}
的包,因此需要作为 san-ssr 的 peer 来安装。例如:
npm i san-ssr san-ssr-target-php
已知问题
- script 元素内容不可在组件间传递。即 script 内不可引用组件,也不可包含 slot。
贡献指南
开发起步
欢迎任何类型的 Issue、完整的 Pull Request、或者不完整的 Pull Request。可以按照下面的步骤开始开发:
- 克隆本仓库并
npm install
- 在 san-html-cases 下添加你的测试样例,以 node_modules/san-html-cases/src/array-literal 为例
- 通过
./bin/debug array-literal
来查看 SSR 结果。输出包括:- 预期输出。即 node_modules/san-html-cases/src/array-literal/expected.html 的内容。
- 从 JavaScript 组件代码编译到 render 代码并渲染得到的内容。
- 从 TypeScript 组件代码编译到 render 代码并渲染得到的内容。
- 从组件 Class 编译到 render 代码并渲染得到的内容。
- 从组件 Class 编译到 render 函数并渲染得到的内容。
- 如果 debug 符合预期,可以运行
npm run e2e
来查看其它样例是否仍然正常。 - 如果一切正常,运行
npm run check
来做最后的编码风格检查,和完整的测试。 - 如果能够通过那么 CI 就应该能通过,请发 PR 到本仓库。
debug 进阶
准备步骤:
- 添加
export PATH=$PATH:./bin
到你的 Shell 配置里。 - 让你的 zsh 进入项目目录后自动
source ./bin/auto-complete
(如果你想自动补全 case 名字的话)。可以自定义 chpwd() 方法来实现。
debug 命令:
debug array-literal
来执行这个 case 的所有编译方式:- 从 component.js 编译到 ssr.js 并执行 SSR 和 assert 结果
- 从 component.ts 编译到 ssr.js 并执行 SSR 和 assert 结果
- 从 component.js 编译到 render 函数并 SSR 和 assert 结果
render-by-source.js array-literal
来跳过编译,直接执行 ssr.js 并 assert 结果。用于手改 ssr.js 调试。render-onthefly.js array-literal
来把这个 case 编译到 render 函数并 SSR 和 assert 结果。
注意:
- 如果没能把 ./bin 添加到 PATH,则执行命令需要全路径,例如:
./bin/debug array-literal
- 如果没能执行 ./bin/auto-complete,则没法 Tab 自动补全 array-literal