1.0.0-alpha.14 是 Element 与 Router 的仓库基线。@alpha dist-tag 服务于当前 1.0 预发布——具体版本用 npm view @openelement/create dist-tags 核实。 registry 真值以
docs/release/release-state.json为准,不提供从 0.x 的受支持迁移路径。
安装
四条命令跑起应用:
npm create @openelement my-app
cd my-app
pnpm install
pnpm dev安装命令解析到的版本登记在 docs/release/release-state.json(仓库的 registry 核验真值)中:脚手架把 @openelement/* 的 caret 范围(以该版本为下限)写进生成的 package.json,不需要任何额外旗标,后续 1.0.0 预发布版本靠 pnpm update 到手。
脚手架只有一种形态:Tailwind-ON——接好 preset 的 vite.config.ts、app/styles/theme.css 这张 @theme 角色表(语义角色落在 Tailwind 默认尺度上),以及精确的 tailwindcss / @tailwindcss/vite 开发依赖。没有旗标,也没有第二种模板:样式面不是脚手架变体。去掉 Tailwind 是受支持的项目内改动:把 openelement.config.ts 里的 tailwind 指向你自己的样式表,或删掉该键,让 app/styles/tokens.css 这条 token 约定为文档提供 token。
生成的项目是纯 Node/pnpm 应用(ADR-0161):脚本由 Node.js 24.2+ 与 pnpm 驱动——Node 24.2 是打包产物 engines 声明、CI 实际运行过的验证下限(Router CLI 依赖 Node 24.2.0 引入的
import.meta.main;.node-version钉住 24.18 开发线)。bootstrap 命令本身就是一次普通的 Node 调用,整条流程只需要 Node 与 pnpm;早先的 Deno bootstrap 已随 2026-10-03 的 ADR-0161 修订被退役。
只要 element 当库用
脚手架是可选的。只想要组件运行时的项目安装一个包即可,全程接触不到 Router:
pnpm add @openelement/element- Vite 项目通过包的 Vite 接缝挂载编译器:
import { element } from '@openelement/compiler/vite',把element()加进plugins。该插件在构建期把每个组件的 TSXrender()编译成 Part Program。 - 其他打包器通过
@openelement/compiler以编程方式驱动同一套编译器——即 Vite 插件自己调用的 TSX-to-Part-Program 内核——再把产物接进自己的流水线。 - 产物是标准 Custom Elements。 编译后的组件就是一个用
customElements.define注册的普通类,产出的 bundle 可以直接进任何页面或框架,无需内嵌任何运行时。这条路每轮发布都会验证:打包产物消费者验收会单独安装@openelement/element(无 Router、无脚手架),编译一个组件,再从独立的纯 HTML 页面在三个浏览器里加载该 bundle。
探索
构建
pnpm build 把可部署的站点产出到 dist/——每条静态路由的预渲染 HTML、public/ 下按原样复制的内容,以及应用含 island 或请求时路由时一并生成的客户端 chunk 与服务端入口。那个目录就是产物:可以上传到任意静态托管,或让 Node/Workers 部署指向 dist/server/index.js。
两个脚本覆盖构建与运行循环:
pnpm build # 预渲染到 dist/(需要时另有 dist/client、dist/server)
pnpm start # 起真实构建产物,包含请求时路由校验改动应该用 pnpm start:它起的是与生产一致的输出,并把动态路由与表单 POST 分派给生成的服务端入口。若构建产物没有请求时路由,router 命令还带一个纯静态模式——openelement start --mode=preview——它拒绝带服务端的构建,而不是悄悄把它藏起来。端口取自 OPEN_ELEMENT_PORT(回退到 PORT,默认 4173),host 取自 OPEN_ELEMENT_HOST。
上线前,pnpm check 对应用做类型检查,pnpm test 跑测试;两者都已在 starter 的脚本里接好,无需额外配置。完整的输出契约——构建写了哪些文件、每个文件回答什么——见部署。