@getforma/create-app

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

Create a new Forma app — Rust + TypeScript SSR framework

原始使用文档
文档目录11 节
  1. Usage
  2. Options
  3. Templates
  4. What You Get
  5. Development
  6. Part of the Forma Stack
  7. Frontend (TypeScript)
  8. Backend (Rust)
  9. Full Framework
  10. License
  11. Source templates and published artifacts

@getforma/create-app

npm version CI License: MIT

Scaffold a new Forma application — Rust server + TypeScript frontend, fully wired.

Where this sits. One repository, eight coordinated source packages:

TS/JSX → @getforma/compiler → FMIR 3 → forma-ir → forma-server → HTML
         @getforma/build joins the assets       @getforma/core adopts islands
         @getforma/create-app supplies the templates; forma-ir-derive types props

You are here: the front door. New to the stack? Read the stack architecture — it explains the pipeline. All eight source packages live in getforma-dev/forma and publish as one set. Existing 0.6.x projects can follow the 3.0 template migration.

Usage

Use the coordinated 3.2.0 CLI. For a connected native router application:

npx @getforma/[email protected] my-routed-app --template native-router

For unpublished source changes, contributors use the packed candidate workflow.

npx @getforma/[email protected] my-app
cd my-app

Then:

# Build the frontend
cd admin && npm ci && npm run build && cd ..

# Start the Rust server
cargo run

Open http://localhost:3000. All templates bind to 127.0.0.1 by default; the dashboard can opt in to a wider bind with FORMA_HOST, and warns when you do, because its /api/* routes have no authentication.

Options

npx @getforma/[email protected] my-app --template dashboard
npx @getforma/[email protected] my-app --template minimal
npx @getforma/[email protected] my-app --dry-run
npx @getforma/[email protected] --help
npx @getforma/[email protected] --version

Project names must start with a lowercase letter and use only lowercase letters, digits, hyphens and underscores, at most 64 characters. The name becomes the crate's name, so the CLI also refuses what cargo refuses for a new package (a Rust keyword such as fn, test, a build directory name such as build) and a Windows device name (con, nul); its message names the rule. It checks the name before writing anything, and refuses to write into a path that already exists.

Templates

TemplateRenderingDescription
dashboardExplicit Browser renderingDevOps admin panel — 4 pages, 8 API routes, SVG chart, Tailwind CSS, Gruvbox theme, 16 Playwright tests
minimalBrowser, or native SSR with npm run build:ssrRust server + a Counter page and a static About page
native-routerNative SSR with optional owned navigationPersistent layout, typed owner branches, ordinary links and history

native-router is included in 3.2.0; it is absent from published 3.0/3.1 archives. For unpublished changes use the documented packed candidate workflow and select --template native-router from that candidate CLI. The 3.2 set adds @getforma/router to this template and the dashboard. The dashboard remains an explicit Browser application, with retained layout and routed page ownership. The minimal template keeps its existing dependency graph and rendering behavior. See its ownership and deployment guide and the connected routing walkthrough.

The dashboard explicitly uses client rendering. The FMIR compiler walks source rather than executing it and accepts only the documented native subset. It refuses unsupported native source with a coded diagnostic; it does not emit an empty placeholder or silently change a native route to client rendering. The minimal template demonstrates native rendering with declared island state; see the admitted subset and the template rendering guide when choosing a mode for a new template.

What You Get

  • Rust server (src/main.rs) — Axum + forma-server: page rendering with a bound PageHandle<Props> (or render_browser_shell for an explicit Browser route), each page a PageResponse carrying its per-request CSP nonce and Cache-Control: no-store, asset serving from rust-embed, no service worker, and a tracing subscriber that logs every render error by code and route
  • TypeScript frontend (admin/src/) — FormaJS with JSX, signals, components
  • Build pipeline (admin/build.ts) — @getforma/build: bundling, content hashing, Brotli/gzip, manifest, in strict mode, so a construct the server cannot render fails the build with its code and line
  • A .gitignore that covers build output, secrets and (for the dashboard) Playwright artifacts — and deliberately does not ignore Cargo.lock
  • Lockfiles (admin/package-lock.json and Cargo.lock) holding the exact versions this repo's scaffold gate built and served, so a new project starts from a tested set rather than whatever resolves that day

Development

npm test        # structural tests — builds the CLI explicitly first
npx tsc --noEmit

The candidate gate needs a network and a Rust toolchain. From the repository root, build and commit the source, then use a fresh artifact/work directory:

npm run build
node scripts/candidate-scaffold.mjs pack /absolute/path/to/candidate-artifacts
# Use the record SHA-256 printed by pack and this checkout's full Git commit.
node scripts/candidate-scaffold.mjs run /absolute/path/to/candidate-artifacts RECORD_SHA256 COMMIT /absolute/path/to/candidate-work /absolute/path/to/report.json

CI always runs the full candidate suite on Linux and Windows. The separate registry lane runs the actual published CLI when all version-appropriate coordinated packages exist. Missing or skipped candidate jobs fail the release gate. The source lock seeds are never passed directly to an unpublished registry installation.

That scaffolds each template into a temp directory, installs from the template's lockfile with npm ci, builds the frontend, runs cargo check --locked, then starts each compiled server and reads its responses: the minimal template must serve real server-rendered markup after build:ssr, the dashboard must serve each page as its declared browser shell whose CSP nonce matches the script tag; native-router must retain its layout through typed navigation in all three browser engines, and every page must answer Cache-Control: no-store with a fresh nonce on each fetch, register no service worker, and leave /sw.js to forma-server's retiring worker. It also runs npm audit signatures over each template's install, fails on any use of deprecated warning from the template's Rust, checks that a construct the server cannot render fails the minimal template's strict build, and that the minimal server refuses to start on a truncated module and answers a failed render with its own 500, carrying neither the error nor an empty shell. A distinct handler value of 7 must appear in raw SSR HTML; missing/wrong props and unbound routes must stop before a listener opens. The packed native-island check adopts the server value without initial writes and checks that the static route requests no code in all three engines. The dashboard tooltip check keeps API values as text under enforced Trusted Types. The current eight-package candidate gate requires all 24 heavy controls plus the structural suite, with no skips. Historical 3.0/3.1 sets retain their original controls.

DocumentWhat it is
CONTRIBUTING.mdSetup, the gates, and what a reviewer will ask
docs/TEMPLATES.mdTemplate anatomy, what the scaffolder rewrites, how to add one
docs/RENDERING-PHASES.mdExplicit Browser and native SSR modes, and the admitted compiler subset
Stack architectureThe whole pipeline and its reasoning. Start here if you are new.
Testing policyThe standard every test in this stack is held to

Part of the Forma Stack

Frontend (TypeScript)

PackageDescription
@getforma/coreReactive DOM library — signals, h(), islands, SSR hydration
@getforma/compilerFMIR generation, coded diagnostics and esbuild SSR integration
@getforma/buildProduction pipeline — bundling, hashing, compression, manifest
@getforma/routerOptional browser/native navigation and persistent layouts

Backend (Rust)

PackageDescription
forma-irFMIR binary format, structural validation and native Rust walker
forma-serverAxum middleware: SSR, asset serving, CSP headers

Full Framework

PackageDescription
@getforma/create-appThis package — scaffolds the full stack

License

MIT

Source templates and published artifacts

The checked-in templates use the declared-props and finalized Pages APIs. Minimal declares a Counter island over its static home markup and a separate empty-props About page. The native handler starts at 7 while explicit Browser mode starts at 0. The published 3.0.0 set includes integrated island adoption and static-route checks; later candidates require their own packed qualification.

Source template locks are explicitly identified seeds at the coordinated package version. They retain every external registry checksum and omit only the known Forma candidate checksums, which cannot exist before the archives are packed. Release packing seals those entries from actual archive bytes, validates the shipped locks, and restores all ten source files. The source-only template-lock-seeds.json marker is never shipped. Use the packed candidate scaffold workflow for local end-to-end development; copying source templates by hand does not produce an installable unpublished candidate set.

The scaffolder writes a separate application identity into admin/build.ts. Valid worker names stay unchanged; accepted project names with underscores or 64 characters use a readable prefix plus a deterministic SHA-256 suffix. This preserves accepted CLI names without merging distinct cache namespaces. The server's enabled worker must use this app value with sw::configure_for_manifest(worker, &manifest) before binding; templates leave workers off. See compatibility and migration.

Verified by: tests/scaffold.test.ts, scripts/release-template-lock.test.mjs at the repository root, and the exact-artifact P17 template run.

版本与发布记录

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

@getforma/create-app 是什么?

Create a new Forma app — Rust + TypeScript SSR framework

如何安装 @getforma/create-app?

在项目目录运行 npm install @getforma/create-app,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 create-app、create-forma-app,可以用 npx create-app 直接运行。

@getforma/create-app 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/getforma__create-app 是否存在。

@getforma/create-app 支持 ESM 还是 CommonJS?

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

@getforma/create-app 需要什么版本的 Node.js?

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

@getforma/create-app 可以商用吗?

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

@getforma/create-app 的下载量有多少?

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

@getforma/create-app 还在维护吗?

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