@getforma/core

中文文档
3.2.0发布于 2026/10/28MITTypeScriptESM + CJS构建来源已验证近 30 天下载 1万

Real DOM reactive library — fine-grained signals, islands architecture, SSR hydration. No virtual DOM, no diffing. The CDN HTML runtime uses a CSP-safe allowlist expression interpreter with zero eval. Bundle sizes are measured by scripts/check-size.mjs.

原始使用文档
文档目录10 节
  1. Install
  2. Three ways to use it
  3. Why FormaJS
  4. Measured, not asserted
  5. Documentation
  6. Part of the Forma Stack
  7. Frontend (TypeScript)
  8. Backend (Rust)
  9. Full Framework
  10. License

FormaJS

CI npm Socket Badge License: MIT

Reactive DOM library with fine-grained signals. No virtual DOM — signals update only the DOM nodes that changed. Components run once.

Where this sits. One product, one repository, eight source packages (including the optional router):

TS/JSX → @getforma/compiler → FMIR (binary) → forma-ir walker → HTML → @getforma/core adopts it
         packages/compiler                    crates/forma-ir          packages/core

You are here: the client runtime — signals, h(), islands, hydration, and the zero-build HTML runtime. It works entirely on its own; the rest of the stack is opt-in. New to the stack? Read the 3.0 architecture first. The Forma workspace also contains the compiler, build pipeline, Rust crates and scaffolder.

import { createSignal, h, mount } from "@getforma/core";

const [count, setCount] = createSignal(0);

function Counter() {
  return (
    <button onClick={() => setCount((c) => c + 1)}>
      {() => `Clicked ${count()} times`}
    </button>
  );
}

mount(() => <Counter />, "#app");

No re-renders. No dependency arrays. No useMemo. The button text updates because it reads count() inside a reactive function — nothing else in the tree is touched.


Install

Install the coordinated 3.2.0 core:

npm install @getforma/[email protected]

Add the optional router for client navigation. The routing guide explains browser rendering, islands and native navigation; core-only applications do not need the router.

For the separate stable 2.1.0 runtime, the following URLs are retained only as historical examples. They use the old automatic lifecycle, not the explicit 3.0 mount contract shown below. For current no-build usage, serve the dist/formajs-runtime.global.js artifact from your qualified installed package:

<!-- jsDelivr (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/@getforma/[email protected]/dist/formajs-runtime.global.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/@getforma/[email protected]/dist/formajs-runtime.global.js"></script>

Production: Pin the qualified version instead of a moving dist-tag.

Any bundler works — Vite, esbuild, tsup, webpack, Rollup. FormaJS ships standard ESM and CJS via package.json exports. No plugins, no special config. For JSX, set jsx: "react", jsxFactory: "h", jsxFragmentFactory: "Fragment".

Gzipped sizes, measured by npm run check:size on the FORMA-294 core candidate at 1d204ba4 on 2026-10-25 (the subsequent opt-in decision changes no core runtime bytes). That script walks the real ESM import graph, weighs shared chunks, and fails if any entry exceeds its limit:

ArtifactGzippedCI limit
@getforma/core entry + every chunk it imports48.6 KiB (49,796 B)49,926 B
CDN HTML runtime (formajs-runtime.global.js)40.1 KiB (41,113 B)41,500 B
CDN HTML runtime, hardened (formajs-runtime-hardened.global.js)39.4 KiB (40,384 B)40,500 B
CDN browser ESM (forma.esm.js, inlines alien-signals)47.6 KiB (48,776 B)49,136 B
Preview frame runtime (formajs-frame.global.js, inlined by the server)38.9 KiB (39,867 B)40,000 B

The core figure is untree-shaken — it is everything dist/index.js pulls in. A bundler that drops what your app does not import ships less. @getforma/build still refuses routes above 28,420 B gzip -9 of Forma code. The 3.1 performance decision records the earlier effects delivery costs. The separate FORMA-294 decision accepts 584 B of package growth and raises only its package cap by 512 B, from 49,414 to 49,926 B. The optional helper itself is excluded from main; splitting its shared dependencies creates most of the transport increase. Template compilation is off by default and remains subject to every route budget. Original failed measurements remain failed; package caps are separate from route budgets.

For historical comparison, the 3.0.0-dev build at 91a50157 on 2026-10-16 measured 48,602 B core, 39,203 B runtime, 37,629 B hardened runtime, 48,836 B browser ESM and 38,687 B frame runtime. Its Counter and indexed SSR routes measured 26,213 B and 28,071 B of Forma code. The former 28,100 B N2 gate and original 50 ms N3 condition belong to that L-64 decision; they are not retroactively changed by the 3.1 decision. The core and browser ESM figures had grown from 29,515 and 28,369 B at 2.1.0 with strict island activation (FORMA-104) and the declared island state block (FORMA-103). Measured sizes can change; a test keeps the current table's CI limits aligned with the gate script.

Verified by src/__tests__/docs-truth.test.ts > "the size table quotes the limits the CI gate actually enforces"


Three ways to use it

All three share the same signal graph and reactive engine. Pick one, or mix them.

What it looks likeNeeds
JSX<button onClick={…}>{() => count()}</button>a bundler with a JSX transform
Hyperscripth("button", { onClick: fn }, () => count())a bundler
HTML runtime<button data-on:click="{count++}">a runtime script and an explicit mount call

JSX compiles to h() — same function, no JSX-specific runtime. The HTML runtime binds reviewed markup handed to mountMarkup() to the same signals. Loading the script binds nothing by itself.

<script src="/vendor/formajs-runtime.global.js"></script>
<main id="counter">
  <div data-forma-state='{ "count": 0 }'>
    <p data-text="{count}"></p>
    <button data-on:click="{count++}">+1</button>
    <button data-on:click="{count = 0}">Reset</button>
  </div>
</main>
<script src="/counter.js"></script>

counter.js starts the reviewed counter explicitly (serve this script under your CSP):

const root = document.getElementById('counter');
const counter = FormaRuntime.mountMarkup(root, FormaRuntime.trustedHtml(root.innerHTML), { tier: 'reviewed' });
// counter.update(FormaRuntime.trustedHtml(nextMarkup)); counter.unmount();

The mount grants no fetch, outside-DOM access or navigation unless requested. No build step is required. → docs/HTML-RUNTIME.md for every directive and the expression grammar.

Verified by src/__tests__/readme-examples.test.ts > "the intro counter works without eval"


Why FormaJS

Components run once. No virtual DOM or component-tree diffing. Keyed lists still reconcile their rows. h('div') returns an actual HTMLDivElement. When a signal changes, only the specific text node or attribute that reads it updates — not the component, not the tree.

Fine-grained reactivity. Powered by alien-signals 3.x. The signal graph tracks dependencies automatically. No dependency arrays, no stale closures, no useCallback / useMemo ceremony.

Three entry points, one engine. Use JSX or hyperscript for components, or explicitly mount reviewed HTML markup. Native SSR additionally requires declared props and the compiler’s admitted subset.

Islands over SPAs. Compiled activateIslands() validates each original SSR region before activation: successful adoption makes zero initial DOM writes, mismatches refuse without repair, and failures remain isolated per island. Load work cooperatively yields between whole islands; await activateIslands() for requested load completion. Deferred triggers (visible, idle, interaction) settle readiness once armed; disposal releases owned work. → docs/ISLANDS.md

CSP-safe. The HTML runtime evaluates expressions with an allowlist AST interpreter. Zero eval(), zero new Function(), zero with() in every shipped artifact — there is no opt-in fallback to leave switched on by mistake, because the fallback was deleted. Asserted by scripts/verify-dist.mjs, which greps the built files as the last step of npm run build, and by a Playwright spec that serves the flagship fixture under a real CSP header.

Verified by src/__tests__/runtime-csp-default.test.ts > "no build can reach new Function, with any configuration" Verified by src/__tests__/build-artifacts.test.ts > "no build emits new Function or a with() scope wrapper"

What FormaJS is not: a framework with opinions about routing, data fetching or state management. It is a reactive DOM library. You bring the architecture.

Measured, not asserted

npm run bench runs the hot-path suite in bench/. The numbers — each with the run-to-run noise floor next to it, so a later comparison can tell a regression from a bad afternoon — live in docs/PERFORMANCE.md. They are historical happy-dom figures, not current browser timings. Strict adoption now uses connected, matching fixtures and a different transaction; no new measurement or comparison against the old adoption baseline is claimed.

  • A write that changes nothing does nothing. An equal-value write never reaches an effect, and costs orders of magnitude less than one that does. Benchmarked by: bench/reactive.bench.ts > "write a CHANGING value, effect runs (×500)"
  • batch() collapses repeated writes to one flush. It does nothing for writes to 100 different signals, which is the correct result. Benchmarked by: bench/reactive.bench.ts > "one signal, 100 writes, batched (×30)"
  • A keyed list update that changes no keys and no order takes the reconciler's fast path, and costs a fraction of the same rows reordered. Benchmarked by: bench/list.bench.ts > "same keys, same order — reconciler fast path"
  • The historical adoption baseline was cheaper than its CSR control, with HTML parsing subtracted. This measured the retired walker; it does not establish the strict transaction's current cost. Benchmarked by: bench/hydrate.bench.ts > "1000 rows: parse + adopt by data-forma-key"
  • The historical benchmark measured the CSP-safe interpreter faster than the eval path it replaced — and it needs no unsafe-eval in your CSP. Benchmarked by: bench/expression.bench.ts > "8 count-dependent expressions: write → evaluate → text (×20)"

Documentation

DocumentWhat it answers
docs/API.mdh(), signals, control flow, stores, components, async, portals — and the four unsanitized escape hatches
docs/HTML-RUNTIME.mdEvery data-* directive, and the CSP-safe expression grammar with its limits
docs/ISLANDS.mdHydrating server-rendered HTML, seeding signals from server data, keyed list adoption
docs/CDN-AND-EXPORTS.mdWhich CDN build to load, and what each subpath export contains
docs/COMPARISONS.mdComing from React, and how this differs from Solid
docs/STABILITY.mdShipped APIs, experimental compatibility, and removed entry points
docs/PERFORMANCE.mdBenchmarked hot paths, with noise floors
SECURITY.md · CSP.mdThreat model; running under a strict Content-Security-Policy
docs/README.mdThe full documentation index, including design records

Examples: examples/ — counter, counter-jsx, csp, todo, data-table.


Part of the Forma Stack

Frontend (TypeScript)

PackageDescription
@getforma/coreThis library — reactive DOM, signals, islands, SSR hydration
@getforma/compilerFMIR compiler and esbuild SSR plugin
@getforma/buildProduction pipeline — esbuild bundling, content hashing, compression, manifest

Backend (Rust)

PackageDescription
forma-irFMIR binary format — parser and native HTML walker
forma-serverAxum middleware — SSR page rendering, asset serving, CSP headers

Full Framework

PackageDescription
@getforma/create-appnpx @getforma/create-app — scaffolds a Rust server + TypeScript frontend project

License

MIT

版本与发布记录

@getforma/core 共发布 45 个版本,首次发布于 2026/03/14;过去 12 个月发布了 45 个版本。最新版本附带 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/core 的常见问题

@getforma/core 是什么?

Real DOM reactive library — fine-grained signals, islands architecture, SSR hydration. No virtual DOM, no diffing. The CDN HTML runtime uses a CSP-safe allowlist expression interpreter with zero eval. Bundle sizes are measured by scripts/check-size.mjs.

如何安装 @getforma/core?

在项目目录运行 npm install @getforma/core,或使用 pnpm add / yarn add / bun add。

@getforma/core 支持 TypeScript 吗?

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

@getforma/core 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

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

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

@getforma/core 可以商用吗?

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

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

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

@getforma/core 还在维护吗?

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