react-ui

React UI

对于任何会渲染 UI 的 val，除非用户另有说明，否则优先使用 .tsx 文件中的 React 组件构建。templates/react-hono-starter 模板已为此配置好——从那里开始使用 remix_val，而不是从头构建。

文件约定

将标记、样式和脚本放在实际文件中——避免使用模板字面量字符串（例如 new Response(\...`)`）。模板字符串中的代码没有语法高亮、Lint 检查或类型检查，也无法进行审查。

• .tsx — React/JSX 组件，以及包含逻辑或交互功能的任何 UI
• .html — 纯静态标记
• .ts — 服务端代码和脚本

在 .tsx 文件中逐个组件构建 UI。组合小型组件，而不是渲染一个庞大的页面。

样式：Twind + Tailwind

优先使用 Twind 在运行时应用 Tailwind 工具类——无需构建步骤。将脚本添加到 HTML 外壳中：

<script src="https://cdn.twind.style" crossorigin></script>

然后在 JSX 中直接使用 Tailwind 类：

<div className="flex items-center gap-4 p-6 rounded-lg bg-white shadow">
  <h1 className="text-2xl font-bold">Hello</h1>
</div>

除非用户另有说明，否则避免使用内联 <style> 标签、CSS-in-JS 对象或单独的 .css 文件。

提供资源：版本化且不可变

使用 std/utils 中的 serveImmutableFile 提供客户端模块——浏览器会以不可变方式缓存这些模块，而发布时会递增 val 的版本，从而自动使缓存失效（完整模式见 client-side-js 技能）。一个永不缓存的 frontend/root.tsx 外壳（hono/jsx）会使用 immutableFileUrl 为入口文件和 favicon 添加时间戳：

// frontend/root.tsx — in the Root() HTML shell:
<script src={immutableFileUrl("/frontend/index.tsx")} type="module" />

// index.ts:
app.get("/", (c) => c.html(Root()));
app.get("/__immutable/*", (c) => serveImmutableFile(c.req.path));

查看源代码链接

每个 UI val 都应提供一种方式，让用户查看并 remix 其源代码。以下两部分缺一不可：

1. 后端路由：

   import { parseVal } from "https://esm.town/v/std/utils/index.ts";
   app.get("/source", (c) => c.redirect(parseVal().links.self.val));
   

2. 前端中的可见链接：

   <a href="/source">view source</a>
   

固定 React 版本

常见错误 "Cannot read properties of null (reading 'useState')" 表示某个 React 子依赖加载了不同版本的 React。将所有 React 相关导入固定到 18.2.0：

import SomeLib from "https://esm.sh/[email protected],[email protected]";

资源

不要使用可能失效的外部图片或托管资源。优先使用：

• Emoji 或 Unicode 符号
• 内联 SVG
• 通过 CDN 加载的图标字体（Lucide、Font Awesome）

显示客户端错误

若要将浏览器错误发送回 val 日志（可通过 get_logs 查看），请在 HTML 外壳中加入此脚本：

<script src="https://esm.town/v/std/catch"></script>

验证更改

编辑 UI val 后，调用 fetch_val_endpoint 确认页面渲染无误，然后检查 get_logs 中是否有客户端错误。两项检查都完成后，才能报告更改已完成。