# 模板与多框架组合

十三种微应用目标、可用 shell、生成的适配器，以及各模板的范围。

版本、变更与要求见 [Framework 3.2 与 CLI 1.0](/zh-cn/docs/guides/releases/)。


<span id="catálogo-implementado"></span>

<span class="section-anchor" id="section-1"></span>

## 已实现的目录

CLI 接受十三种微应用名称。shell 选择额外包含 `astro` 和 `next`。支持某个名称意味着存在生成路径，不代表各框架在编译器、SSR、生态或生命周期上完全等价。

| 目标 | 生成的组件与注册方式 | 对应生成的 shell |
| --- | --- | --- |
| `react` | `App.tsx`，`wuReact.register`，显式提供 React/ReactDOM 运行时 | React |
| `vue` | `App.vue`, `wuVue.register` | Vue |
| `svelte` | `App.svelte`, `wuSvelte.registerSvelte5` | 通用 JavaScript |
| `solid` | `App.tsx`, `wuSolid.register` | Solid |
| `preact` | `App.tsx`, `wuPreact.register` | Preact |
| `qwik` | `App.tsx`, `wuQwik.register` | Qwik |
| `lit` | `App.ts`, `wuLit.register` | Lit |
| `vanilla` | 应用模块，`wuVanilla.register` 配合 render 函数 | 通用 JavaScript |
| `angular` | Angular 组件与配置，`registerStandalone` | Angular |
| `alpine` | 使用 `@alpinejs/csp` 的 JavaScript，`wuAlpine.register` | 通用 JavaScript |
| `stencil` | 自定义元素与 `wuStencil.register` | 通用 JavaScript |
| `htmx` | HTML/JS 模块，`wuHtmx.register` | 通用 JavaScript |
| `stimulus` | 控制器模块，`wuStimulus.register` | 通用 JavaScript |

这些扩展名对应快速模式：在兼容时启用 TypeScript。向导可以生成 JavaScript 变体，但 Alpine、HTMX 和 Stimulus 不提供 TypeScript 选择。

<span id="versiones-del-catálogo-11"></span>

<span class="section-anchor" id="section-2"></span>

## 1.1 目录版本

```sh
wu catalog
wu catalog --json
```

目录是 create、add、install、upgrade 和自动发现的统一来源。它声明 WU Framework `^4.0.0`、Preact `^11.0.0`，以及 Angular 22 所需的 TypeScript `~6.0.0`。JSON 包含版本范围和保留旧范围的原因；生成时不会查询 npm 来选择版本。

<span id="qué-constituye-una-microapp-generada"></span>

<span class="section-anchor" id="section-3"></span>

## 生成的微应用包含什么

生成器写入可识别的软件包、Vite 配置、`index.html`、演示组件和注册入口。HTML 的独立运行容器与适配器期待的选择器一致，因此应用既能用自身工具链运行，也能从 WU shell 挂载。

不会自动生成源 `wu.json`。开发时服务器可以提供契约为空的虚拟清单，生产构建则写入包含生成入口的清单。要使用契约 imports/exports 或权限，请编写显式清单，并确认申请与宿主 grants 匹配。

<span id="particularidades-que-importan"></span>

<span class="section-anchor" id="section-4"></span>

## 需要注意的差异

<span class="section-anchor" id="section-5"></span>

### React

入口把 `React` 和 `ReactDOM` 传给适配器，保持同一运行时身份。避免适配器副本解析到与组件不同的实例。生产共享依赖时，还必须包含实际导入的完整 specifier。

<span class="section-anchor" id="section-6"></span>

### Angular

应用骨架生成 `tsconfig.json` 和 `tsconfig.app.json`、导入编译器、准备应用配置，并向 standalone 适配器传入创建函数。Angular 编译需要专用集成；把这些文件当作装饰而删除，可能导致构建缺少预期代码。

<span class="section-anchor" id="section-7"></span>

### Stencil

当前模板直接写入继承 `HTMLElement` 的类并注册自定义元素。它使用 Stencil 适配器，但不等于生成包含完整流水线的 Stencil 编译器项目。需要该流水线时，请显式集成并验证构建入口。

每个 Stencil 应用注册 `wu-stencil-<name>`，不安装 `@stencil/core`。Angular shell 声明 `rxjs`，Solid shell 声明其 Babel preset，中立 shell 不添加 Svelte。Vanilla 模板将状态和 WU 上下文传递给渲染及组件。

<span id="alpine-y-htmx"></span>

<span class="section-anchor" id="section-8"></span>

### Alpine 与 HTMX

Alpine 使用 CSP 分发版本。HTMX 入口禁用求值和 script 标签，在导入运行时前完成配置，并避免自动指示器样式。这些选择属于应用骨架的一部分；重新启用相关功能时，需要检查与宿主策略的关系。

<span class="section-anchor" id="section-9"></span>

### Qwik

开发环境有使用 Qwik 优化器的编译路径。作为 WU 微应用的模板在客户端挂载，本身不承诺完整的宿主 SSR 或 resumability 架构。

<span id="shell-astro-o-next"></span>

<span class="section-anchor" id="section-10"></span>

## Astro 或 Next shell

```bash
wu create conocimiento --template react --shell astro
cd conocimiento
wu add vue explorador --no-install
wu add lit indicador --no-install
wu install
wu dev --no-open
```

Astro 构建 shell，React、Vue 和 Lit 注册为微应用。宿主决定其挂载和契约；微应用无需采用 shell 的框架。

`--shell next` 使用导出到 `out/` 的静态方案。`--template astro` 和 `--template next` 会失败，因为微应用目录不包含这两个目标。支持 shell 不意味着 WU 会运行 Astro 或 Next SSR 服务器。

<span id="prueba-mínima-de-una-combinación"></span>

<span class="section-anchor" id="section-11"></span>

## 组合的最小验证

构建、加载每个应用、操作演示计数器、切换应用并重新挂载。检查控制台、样式和卸载清理。添加通信后，应同时验证契约允许和拒绝的操作。模板表只是目录；此测试才能确认项目和已安装版本的实际行为。

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-12"></span>

## 实现参考

- `wu-cli/src/config/catalog.zig`
- `wu-cli/src/commands/catalog.zig`
- `wu-cli/src/commands/templates/`
- `wu-cli/tests/scaffold-catalog.test.cjs`
- `wu-cli/tests/vanilla-ctx.test.cjs`