@getforma/compiler

中文文档
3.2.0发布于 2026/10/28MITTypeScriptES Module构建来源已验证近 30 天下载 9230

npm License: MIT

中文使用文档
文档目录19 节
  1. 安装
  2. 建立安全部门改革插件 - formaSsrPlugin
  3. FMIR v3 兼容性
  4. 构建诊断
  5. 只浏览器组件和本地登录
  6. 土著来源和所有权
  7. 封闭值和诊断
  8. 公共入境点
  9. 客户 JSX 模板
  10. 你什么时候需要这个?
  11. 同伴依赖关系
  12. 福玛堆栈的一部分
  13. 前端( TypeScript)
  14. 后端( Rust)
  15. 完整框架
  16. 许可证
  17. 出口产品运输
  18. 只有岛屿浏览器条目(FORMA-105)
  19. 原生导航所有者汇编

@ getforma/ 编译器

npm License: MIT

FMIR 和客户端 JSX 编译器 福玛. Emits binary 模块用于本地 Rust SSR 并降低符合条件的浏览器 JSX 以重用 HTML 模板.

添加 Rust SSR 的编译器; 没有它只运行浏览器应用程序 .

维特插件( V) (formaCompiler, (中文(简体) ), formaServer, (中文(简体) ), compileFormaJSX 财务报告和审定财务报表 transformServerFunctions 在3.0.0中被删除。 使用 @getforma/build 和经认证的路由. 旧插件文档 已存档.

安装

这些例子使用了协调的 3.2.0 软件包设置。 明确选择该版本 :

npm install -D @getforma/[email protected]

建立安全部门改革插件 - formaSsrPlugin

Emits FMIR(Forma Module IR) 二进制文件,用于基于 Rust的服务器侧渲染. 仅需要完整的 Forma 堆栈(forma-ir + 键 forma-server) (中文(简体) ).

import { formaSsrPlugin } from "@getforma/compiler";

// Used by @getforma/build, not typically called directly

使用建设 write: false插件附件 <page>.ir 返回时 outputFiles,与浏览器输出同步,从不自己写入文件. 只有在完整的 esbuild 调用成功后才能公布这些文件 . @getforma/build 处理出版、回滚和观察世代. write: true 被拒绝.

一个被捕获的源图生成了FMIR和浏览器注册元数据. 一个独特的 clientEntryPoint 必须解决与《公约》相同的岛屿宣言 entryPoint;单靠拼写匹配是不够的. 源/类型编辑期间 编译拒绝产品,可以重试。 浏览器路径( E)ssr: false(中文(简体) ) 不使用此变换 。 岛表位于二进制内; 想要作为数据使用的呼叫者 generateRealIr(entry), (中文(简体) ), 返回时 { binary, islands }. (插件通过0. 2. 0 也降下 a) <page>.islands.json 输入输出目录的侧行车——在 已售出的资产树,只读取后 @getforma/build 步骤。 )

FMIR v3 兼容性

编译器释放 FMIR v3 (英语)一个24字节标题, 区域表,以及所需的字节代码、字符串、插槽、岛屿和页面道具 计划 CRC-32涵盖了除自身四字节外的每一字节. 那个作家 基础主/小/patch来自编译器包版本。 读者接受 其自己的主要和作家未成年人达到其自己的水平;补丁号码不限制 兼容性. 3.0.0-dev 财务报告和审定财务报表 3.0.0 两种编码 3,0,0。升级渲染器 先跟随 兼容合同。 。 。 . 使用对齐的编译器和 Rust 软件包并重建旧的 .ir 文档。 V2模块 拒绝重建诊断.

dumpFmir(binary) 输出与 Rust 相同的无损失的条形文字 dump_ir, (中文(简体) ), 包括区旗、未知的可选有效载荷和岛屿扩展字节. IrEmitContext 暴露出用于工具化的策略,密钥路径和源位作者. AST生产汇编载有申报的页码和岛屿合同以及 已验证的密钥路径 。 请求数据受这些声明的约束,而不是 通过被猜出的数字槽ID或匿名槽名. 见 已声明道具 和格式文档 现行电线合同.

构建诊断

这个 可服务器响应子集和诊断目录 定义 编译器可以出版的。 不支持的本地构造失败了 代码,原始来源位置,理由和修复. 没有只有警告的SRS模式 或占位符模块. strict: false 财务报告和审定财务报表 FORMA_STRICT=0 仍被接受为 兼容输入,不能降级出错 .

直接建设插件应用相同的政策. @getforma/build 收藏 在拒绝出版前横跨条目的诊断,写一个可选的 JSON ,并保留先前的良好产出. collectDiagnostics(() => generateRealIr(entry)) 仍为低级别检查;呼叫者必须检查 在发布任何返回的字节之前进行诊断.

可调用列表源也需要本地值: 使用已声明的数组道具或 关闭字面默认信号 。 编译器不评估任意获取器, 过滤器或地图。 退休的BUILD-303/504保留;其历史指导 已存档。 当前列表密钥和行根证明在子集中描述.

只浏览器组件和本地登录

已申报的组件 const Chart = browserOnly(ChartImpl) 从 @getforma/core 必须在可读的编译器中注册 activateIslands 对象。 其打入的道具必须由申报的合同代表. 这个 编译器发布其认证的主机和状态合同而不走它 执行。 不支持的本地成分不会隐含地变成这样 主持人。 未注册或无法说明的边界与 BUILD-610 失败; 旧 BUILD-706/708 滴/壳行为被退役. 只使用浏览器的路由 渲染可以选择 ssr: false 内 @getforma/build。 。 。 .

土著来源和所有权

编译器遵循命名源组件,并支持相对导入和 再出口,包括TypeScript/JSX出口别名. 一揽子执行, 连续构成和构成超过三个内列水平的情况被拒绝. 这个 子集目录 名称和链接 a 阴性,每页诊断都经过固定.

服务器数据通过打入的页面和岛道具输入. 计算服务器值 属于自己宣布的道具; 任意调用、算术、过滤器和地图 本地行走者不按要求时间进行评估。 字符默认信号 并且经过证明的丙种信号可以提供初始的原生值. 关闭客户端 值不是可处理器位。 复制信号获取器名称 范围仍然报告BUILD-503,现在拒绝出版;使用不同的获取器 名称或酌情共同声明.

createList 需要一个可调用源, 证明可读取已声明的数组道具或 已关闭的字面默认信号、属性路径键和稳定自有元素 每个行。 平方阵列源为 BUILD-616;可调用但本地-未证实的数据为 BUILD-610 (英语). 本地作家和客户的收养使用所排放的密钥合同.

限值选择必须通过相同的激活来拥有其选项状态 边界。 独立注册的选项/选择组内容 业主拒绝使用BUILD-617. 普通未注册的自有助手 岛屿和登记内容在无限制选择下继续被接受。 这个 独立岛根和有限剖面修复证明仍然是FORMA-139的 释放门,如子集文档所记录.

封闭值和诊断

编译器可以折叠支持的字面和模块-恒定表达式以及 初始信号值 。 折叠不会把直接价值变成反应 绑定;使用浏览器应该跟踪它的函数。 斯卡尔文本, 属性和条件服从 共享价值规则, (中文(简体) ), 包括 HTML 布尔存在和明确的布尔条件.

一个未知的文本/属性值,无支持道具形状,未解决的组件, 或字面上超过 FMIR 字符串表限制拒绝发布。 没有 发布缺失标记或占位符,并离开浏览器进行修复. 历史位置注射、仅警告和倒置指导保存于 福尔马-101预读。 。 。 .

公共入境点

包根导出汇编( E)formaSsrPlugin, (中文(简体) ), generateRealIr, (中文(简体) ), formaClientPlugin, (中文(简体) ), transformClientTemplates和 明确的工具 API : IrEmitContext 及其计划/关键路径/来源-位置 类型; DIAGNOSTIC_CATALOGUE, (中文(简体) ), collectDiagnostics, (中文(简体) ), diagnosticEntry, (中文(简体) ), formatDiagnostic, (中文(简体) ), makeDiagnostic 及其诊断类型;以及 FMIR 检查/编码(readFmirContainer, (中文(简体) ), dumpFmir, (中文(简体) ), encodeFmirSections, (中文(简体) ), crc32, (中文(简体) ), baseWriterVersion, (中文(简体) ), COMPILER_WRITER_VERSION, (中文(简体) ), FmirContainerError, (中文(简体) ), WriterVersion, (中文(简体) ), FmirSection) (中文(简体) ). 释放包集验证器使用相同的 公众检查API为消费者.

客户 JSX 模板

formaClientPlugin() 是一个经典 JSX 的 Esbuild 插件,其名称为 h 从 @getforma/core配置 jsxFactory: 'h' 注册此插件 并行 formaSsrPlugin() 当建立本地/浏览器对. @getforma/build 仅用 clientTemplates: true;默认关闭。 此选项 需要一个协调的编译器/核心集。 它针对的是经常创建的列表, 其中缓存模板可以偿还帮助者的下载和清理费用. 小型 岛屿应保持正常 h() 除非它们自己的测量支持选择 进来 所有路线规模预算仍然适用,包括编译的建筑.

通道升降机逃出, 静态 HTML 和子节点绑定路径符合条件 直接同步内线内至少包含两个元素的子树 createList 使调用从核心导入。 双参数指数化超载 并识别出三/四参数阵列超载,包括导入 别名。 命名为行帮助者,筑巢功能和无关的JSX仍然很平凡. 目前符合条件的要素是普通的 HTML 容器、 文本格式化、 列表、 清晰的表格部分/ 单元格、 锚、, 按钮, br 财务报告和审定财务报表 hr属性仅限于 class编号 :className, (中文(简体) ), id, (中文(简体) ), title, (中文(简体) ), role缩写 data-*编号 :aria-*。动态属性和唯一 动态子使用现有的核心写法,包括反应函数值 和节点/阵列儿童。 内入 onClick 函数使用授权的 bubbling 点击. 分布、 参照、 样式、 原始 HTML、 URL 属性、 窗体控制、 自定义元素, 外国命名空间、其他事件形式、混合动态子和解析器不稳定 树木保留普通的JSX降低;符合条件的后人仍可能被降低.

初始化器保存了表达式和初始读取器的交互:一个节点的 属性表达式先运行,然后其子被构建并初始化, 然后,它自己的道具和 儿童捆绑初始化。 每个表达式运行一次 只有选择的建筑路径。 直接 await编号 :yield 表达式和同步 或生成器使回调保持正常; 延迟函数机构不是 搬出他们的功能。 缓存的静态子树已经拥有了静态 属性和初始化过程中的父/子内部联系。 密码可以检查这些链接 这个有意与巢穴的区别 h() 建筑,每个建筑都带有 子女后来归父母.

工厂在模块初始化时不进行DOM或信托政策工作. 它懒惰 标记回调使用已有的显式 trustedHtml 用于编译器的薄荷 已逃出字节; 帮助者验证模板下沉的品牌值 . 收养和非HTML倒置 执行原JSX 不评估 标记回调.

所编译的点击每个文档使用一个共享的bubbling收听器. 原画 由路由用品处理器命令组成,每个处理器将其约束要素视为 currentTarget在文档收听者阻止之前停止了传播 处理器; 脱离- 树和未组合的阴影点击无法到达它 。 删除 a 编译行或处置其所有人可撤销其处理器和约束。 这是 编辑事件合同; 本地事件听众选项仍可通过 普通类 h() 树.

原生FMIR由原始来源生成. 收养说明和收养 非 HTML 构建 执行 JSX 原始树; 采用实时更新 和新的公司社会责任创建保留一个所有权/反应图。 生成的助手 来自 @getforma/core/compiled,因此使用协调的核心/编译器集 提供这个子路径。 没有编译模板的应用程序不导入. 服务器通过列表还描述在激活后插入的行 最初的JSX路径. 因此,当前克隆速度适用于客户端创建 列表; 这不是一个被采纳的列表优化.

对于捆绑者整合, transformClientTemplates(source, { filename?, factory?, runtime? }) 返回将 JSX/TSX 转换为在 JSX 降低前的字符串. 默认是 factory: 'h' 财务报告和审定财务报表 runtime: 'transform'; 导入 h 别名 可能由 factory。不支持的输入不变地返回。 直接字符串 API 不抓取文件或应用命名空间包; 集成必须保留 它们的源和命名空间保证。 优先使用 Esbuild 插件 .

generateRealIr(entryPointPath) 驱动组件分析、分辨率、行走 和排放。 这些执行单元,包括: ComponentAnalyzer, (中文(简体) ), walkHTree,信号瞄准镜和导出解析器,是私有的. 直接子路径 进口不是一揽子出口。 运行时间表面被 supported-surface.test.ts; 包裹核查检查已建成的文物.

你什么时候需要这个?

假设需要编译器吗?
学习 FormaJS,建筑原型没有
Rust SSR 为 forma-server是 — 发送 FMIR 二进制
HTML 运行时间 (data-* 指令)不 运行时间处理一切

同伴依赖关系

  • esbuild >=0.17.0 (可选的 —— 用于构建 SSR 插件)
  • @getforma/core ^3.2.0 为现在的未成年人。 补丁差异是相容的.

福玛堆栈的一部分

前端( TypeScript)

软件包说明
@ getforma/ 核心反应 DOM 库 - 信号、 h (), 岛屿、 SSR 水分
@ getforma/ 编译器这个包 h() 优化、申报道具和岛屿、IR排放
@ getforma/ 构建生产管道——捆绑、散货、压缩、明细表

后端( Rust)

软件包说明
福玛尔FMIR 二进制格式 — 剖析器和本地 HTML 行走器
forma 服务器已打入 SSR 和 Axum 响应——页面渲染,资产服务, CSP 头

完整框架

软件包说明
@ getforma/ 创建- appnpx @getforma/create-app – 脚手架 一个 Rust 服务器 + TypeScript 前端工程

许可证

麻省理工学院

出口产品运输

formaSsrPlugin 需要兴建 write: false。在等待成功之后 build() 或者说 rebuild()电话 getSsrEntryProducts(result) 确切结果 对象。 每一个不可改变的记录都确认 犬科源/浏览器条目, ,页,IR输出路径和SHA-256, 排放的岛屿定义和 browserRequired后者基于汇编后的定义,包括: 有条件的岛屿; 未使用的注册不需要静态页面 Java脚本. 此传输本身不会删除浏览器代码或发布文件. 在下面重写只包含岛屿的条目,并构建图表/显示过滤器 使用这些已接受的记录。 运出 @getforma/build 融合 出版完整的产品; 单独调用访问器 发布什么.

访问器拒绝失败结果或替换/修改IR输出. 它回来了 无法创建仅显示浏览器的本地记录; 呼叫者必须需要一个 匹配每个配置的 SSR 条目的记录 。 本地编译失败 无法使用占位符 IR 来建立静态策略 .

永远不要早点出版 onEnd: 后期插件仍可能拒绝结果. 建筑集成可以读取其最后被看守的出版商的记录,毕竟 其它验证钩; 与该周期的图和 显出. 拒绝的监视周期保留先前接受的记录和文件. 编译器未显示可变 onStart 元数据回调.

如果源文件或其分辨率在编译过程中发生变化,则编译器 拒绝这个世代,并称可选 onSourcesChanged(page) 召回电话, 包括已存在另一个编译错误。 定制的表主 可用此通知将新建工程排入当前周期之后 结束。 别等了 rebuild() 内部 onEnd;它可以加入循环,其周期 调用仍在运行中 . @getforma/build 处理两个拆分的回收 和非分块构建, 串联请求, 并在一个不变无效后停止 生成。 注销和处置清理待回收工作.

只有岛屿浏览器条目(FORMA-105)

本地条目可以选择其页并单独命名为核心导入 :

import { mount, activateIslands } from '@getforma/core';
import { HomePage } from './HomePage';
import { Counter } from './Counter';

activateIslands({ Counter });
mount(HomePage, '#app');

配对编译器认证导入, 释放原始本地页面, ,并省略了浏览器产品中的挂载语句。 只有定义 在排放的原生出物中可达到的仍在活化中 注册;有条件的岛屿仍然需要JavaScript. 包装器使用 原申报的组件和捕获的获取器。 进口和模块 初始化保留在原模块中; 没有组件复制或 信号重新创建。 普通捆绑树摇动会去掉未使用的纯页码.

一个单独的 entryPoint 可能同时提供编译时本地挂载 clientEntryPoint 仅仅是激活。 如果两个条目都挂载一个已命名的页面,则 必须通过别名或 桶头。 所有注册身份和警署合同都必须符合, 即使是未使用的注册。 无法证明单独内置的页面功能 该声明身份;取而代之的是只使用激活浏览器形状.

BUILD-611 拒绝使用/指定/出口的挂载结果、筑巢结果或多重结果 挂载、间接挂载别名、命名空间挂载访问、有效目标 参数,以及模棱两可的只激活页面导入。 命名的导入别名 (单位:千美元)import { mount as render }) 得到支持。 一个实际的核心命名空间绑定 可读取静态命名的非挂载成员,包括可选访问。 动态 拒绝通过/出口/变相/更改名称空间的结构 因为他们无法证明山体不存在 仅限类型用途已删除 无效。 这种保守的检查不适用于任意的用户对象. 仅命名的用户函数 mount 被保留下来。 空激活调用仅可单独省去 具有纯余参数的顶级语句; 所需效果必须是 明确声明他们之外。 非空激活根参数和 周围的行为保持原样 在已删除的页面挂载内激活 拒绝。 这些错误以严格模式或不严格模式构建 .

零岛产品记录 browserRequired: false;出版社必须保留 它的 SSR 模式/ IR 在省略 JavaScript/module- preload 链接的同时. 零请求路由还取决于构建的列表和服务器 响应策略; 编译器访问器本身并不能确定该行为。 浏览器路径( E)ssr: false保持正常状态 客户端挂载, 不使用此本地条目重写 .

一个 ebuild 操作中的多个本地条目插件共享一个私有 汇编协调员。 它等待着每道电流 onStart 分析、检查 重叠原始源的快照同意, 并构成原始范围 条目在装入任何文件之前编辑。 每个贡献者的来源和分辨率 警卫在出版前仍然运行;被拒绝的周期不能提供部分 转型权威. 相同的编辑可被复制;相冲突 区域拒绝而不是选择第一个插件.

支持一个新建选项对象的普通相继再利用,如同 与独立选项对象同时建并完成 继续重建的环境。 如果两个设置在重用时中断 相同的选项对象, 分组模糊并失败 BUILD-611。 。 。 . 对同时设置使用不同的选项对象( 和一个新选项对象) 设置失败后 ) 此协调员不添加一个公众 组合插头 API.

协调者从每次原始登记中收集收养信息 装入共享模块,然后用条目编辑的正本来编曲这些钩子 坐标。 与相冲突的可写解码器共享的帮助用户保留其 信号拖拉,但没有得到更精确的授权。 每个单元都有一个卫生设备 钩入,且原生字节/合同不变,仍为 浏览器注册 。 这些编译器的钩子为所运入的严格收养交易提供素材. 浏览器 和包装检查使其与排放分开进行.

原生导航所有者汇编

formaSsrPlugin({ navigationOwner: true, ... }) 被支持的编译器切换 用于 @getforma/build 导航组。 出口经过认证的岛屿 注册而不是激活,并删除编译时间挂载。 一个静态 所有者收到一个空的登记簿而不要求 activateIslands({})。 。 。 . 单独编译的FMIR仍然是本土结构和道具的来源.

车主可以宣布为空 div 与 data-forma-outlet="child", (中文(简体) ), 在每一个注册岛屿之外 复制、筑巢、非空地、动态和 岛屿拥有的渠道被拒绝。 成功 getSsrEntryProducts(result) 记录 包含 navigationOutlet 加上实体申报身份和合同 每一个被排放的岛屿, 允许建筑认证被拆卸的共享岛屿. 这些字段不包含此选入; 普通的静态无 JS 分类 而现有的FMIR字节不变. 使用构建 API 获取完整 身份、完整性和原子出版合同; 仅低等插件 不发布导航组.

版本与发布记录

@getforma/compiler 共发布 32 个版本,首次发布于 2026/03/14;过去 12 个月发布了 32 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
3.2.0latest2026/10/2819 天前
3.2.0-rc.3next2026/10/2719 天前
3.2.0-rc.22026/10/2720 天前
3.2.0-rc.12026/10/2720 天前
3.1.02026/10/2620 天前
3.1.0-rc.32026/10/2621 天前

关于 @getforma/compiler 的常见问题

如何安装 @getforma/compiler?

在项目目录运行 npm install @getforma/compiler,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@getforma/core(^3.2.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getforma/compiler 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getforma/compiler 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@getforma/compiler 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@getforma/compiler 可以商用吗?

@getforma/compiler 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@getforma/compiler 的下载量有多少?

根据 npm 官方下载统计,@getforma/compiler 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,230 次,日均约 308 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getforma/compiler 还在维护吗?

最新版本 3.2.0 发布于 2026/10/28(19 天前);至今共发布 32 个版本,其中过去 12 个月发布了 32 个;首次发布于 2026/03/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。