安装

创建新项目

TIP

官方脚手架是推荐入口。它会创建 Vite 应用，并自动配置 Macro 组件主线。

pnpm create elfui@beta my-app --install
cd my-app
pnpm dev

交互过程中可以选择 TypeScript 或 JavaScript、Macro 或 Chain 组件、CSS/SCSS/Less，以及可选的 Router、Vitest、ESLint 与 Prettier。新项目请选择 Macro。

无需交互直接创建带路由的项目：

pnpm create elfui@beta my-app --router --install

该命令会加入 @elfui/router，并生成 router 模块、页面和导航骨架。需要最小空项目时使用 --bare，它不会生成教学示例。

接入已有 Vite 项目

安装主包和 Vite 编译插件：

pnpm add @elfui/core
pnpm add -D @elfui/vite-plugin

应用的直接运行时依赖只需要 @elfui/core。@elfui/runtime、@elfui/reactivity 和 @elfui/shared 会作为框架内部依赖安装，普通项目不要重复写进 dependencies。

beta.5 兼容

上述单入口从 v0.1.0-beta.6 生效。使用 beta.5 或更早版本时，编译产物仍可能直接引用 @elfui/runtime/internal；pnpm 项目需要继续显式安装同版本 @elfui/runtime，直到 Core 与 Vite 插件一起升级到 beta.6。

// vite.config.ts
import { defineConfig } from "vite";
import { elfuiMacroPlugin } from "@elfui/vite-plugin";

export default defineConfig({
  plugins: [elfuiMacroPlugin()]
});

普通 TypeScript 模块只要导出 defineHtml(...)，插件就会把它编译为 ElfUI Macro 组件：

import { defineHtml } from "@elfui/core";

export const Hello = defineHtml(`<p>Hello ElfUI</p>`);

可选包

包	什么时候安装
@elfui/router	应用需要客户端路由。它独立于 @elfui/core。
@elfui/chain	旧页面、小 demo 或无构建环境需要 Chain 组件。
@elfui/reactivity	完全脱离组件运行时、只使用响应式系统的底层库。普通 ElfUI 应用从 Core 导入。
@elfui/runtime	框架集成或底层 Custom Element runtime 封装。普通 ElfUI 应用从 Core 导入。

完整的包、仓库与工具关系见生态总览。