Hono JSX 服务端渲染指南：异步组件、流式传输与 HTML 生成

hono-jsx by bobmatnyc/claude-mpm-skills

114 周安装量

29 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill hono-jsx

Web应用 JavaScript 框架性能优化

🇨🇳中文介绍

Hono JSX - 服务端渲染

概述

Hono 提供了一个内置的 JSX 渲染器，用于服务端 HTML 生成。它支持异步组件、使用 Suspense 进行流式传输，并能与 Hono 的响应系统无缝集成。

主要特性 :

服务端 JSX 渲染
异步组件支持
使用 Suspense 进行流式传输
自动头部提升
错误边界
上下文 API
零客户端水合开销

何时使用此技能

在以下场景中使用 Hono JSX：

构建服务端渲染的 HTML 页面
创建电子邮件模板
生成静态 HTML
流式传输大型 HTML 响应
构建 MPA（多页面应用程序）

不适用于：交互式 SPA（请改用 React/Vue/Svelte）

配置

TypeScript 配置

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx"
  }
}

替代方案：编译指示注释

/** @jsx jsx */
/** @jsxImportSource hono/jsx */

Deno 配置

// deno.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "npm:hono/jsx"
  }
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

使用 Suspense 进行流式传输

import { Suspense, renderToReadableStream } from 'hono/jsx/streaming'

const SlowComponent: FC = async () => {
  await new Promise(resolve => setTimeout(resolve, 2000))
  return <div>Loaded after 2 seconds!</div>
}

app.get('/stream', (c) => {
  const stream = renderToReadableStream(
    <html>
      <body>
        <h1>Streaming Demo</h1>
        <Suspense fallback={<div>Loading...</div>}>
          <SlowComponent />
        </Suspense>
      </body>
    </html>
  )

  return c.body(stream, {
    headers: {
      'Content-Type': 'text/html; charset=UTF-8',
      'Transfer-Encoding': 'chunked'
    }
  })
})

多个 Suspense 边界

const Page: FC = () => {
  return (
    <Layout title="Dashboard">
      <h1>Dashboard</h1>

      <Suspense fallback={<div>Loading user...</div>}>
        <UserProfile />
      </Suspense>

      <Suspense fallback={<div>Loading stats...</div>}>
        <Statistics />
      </Suspense>

      <Suspense fallback={<div>Loading feed...</div>}>
        <ActivityFeed />
      </Suspense>
    </Layout>
  )
}

import { ErrorBoundary } from 'hono/jsx'

const RiskyComponent: FC = () => {
  if (Math.random() > 0.5) {
    throw new Error('Random error!')
  }
  return <div>Success!</div>
}

const ErrorFallback: FC<{ error: Error }> = ({ error }) => {
  return (
    <div class="error">
      <h3>Something went wrong</h3>
      <p>{error.message}</p>
    </div>
  )
}

app.get('/risky', (c) => {
  return c.html(
    <Layout title="Risky Page">
      <ErrorBoundary fallback={ErrorFallback}>
        <RiskyComponent />
      </ErrorBoundary>
    </Layout>
  )
})

const AsyncRiskyComponent: FC = async () => {
  const data = await fetchData()

  if (!data) {
    throw new Error('Data not found')
  }

  return <div>{data}</div>
}

// 错误边界也能捕获异步错误
<ErrorBoundary fallback={({ error }) => <p>Error: {error.message}</p>}>
  <AsyncRiskyComponent />
</ErrorBoundary>

import { createContext, useContext } from 'hono/jsx'

type Theme = 'light' | 'dark'

const ThemeContext = createContext<Theme>('light')

const ThemedButton: FC<{ label: string }> = ({ label }) => {
  const theme = useContext(ThemeContext)
  const className = theme === 'dark' ? 'btn-dark' : 'btn-light'

  return <button class={className}>{label}</button>
}

const App: FC<{ theme: Theme }> = ({ theme, children }) => {
  return (
    <ThemeContext.Provider value={theme}>
      <div class={`app theme-${theme}`}>
        {children}
      </div>
    </ThemeContext.Provider>
  )
}

app.get('/', (c) => {
  const theme = c.req.query('theme') as Theme || 'light'

  return c.html(
    <App theme={theme}>
      <ThemedButton label="Click me" />
    </App>
  )
})

像 <title>、<meta>、<link> 和 <script> 这样的标签会自动提升到 <head>：

const Page: FC<{ title: string }> = ({ title, children }) => {
  return (
    <html>
      <head>
        {/* 基础头部内容 */}
      </head>
      <body>
        {/* 这些将被提升到头部！ */}
        <title>{title}</title>
        <meta name="description" content="Page description" />
        <link rel="stylesheet" href="/page.css" />

        <div>{children}</div>
      </body>
    </html>
  )
}

// 甚至可以从嵌套组件中提升
const SEO: FC<{ title: string; description: string }> = ({ title, description }) => {
  return (
    <>
      <title>{title}</title>
      <meta name="description" content={description} />
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
    </>
  )
}

const Article: FC<{ article: Article }> = ({ article }) => {
  return (
    <div>
      <SEO title={article.title} description={article.excerpt} />
      <h1>{article.title}</h1>
      <div>{article.content}</div>
    </div>
  )
}

dangerouslySetInnerHTML

const RawHtml: FC<{ html: string }> = ({ html }) => {
  return <div dangerouslySetInnerHTML={{ __html: html }} />
}

// 用法
const markdown = await renderMarkdown(content)
<RawHtml html={markdown} />

import { raw } from 'hono/html'

const Page: FC = () => {
  return (
    <html>
      <body>
        {raw('<script>console.log("Hello")</script>')}
      </body>
    </html>
  )
}

import { Fragment } from 'hono/jsx'

// 使用 Fragment
const List: FC = () => {
  return (
    <Fragment>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </Fragment>
  )
}

// 使用简写语法
const List2: FC = () => {
  return (
    <>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </>
  )
}

import { memo } from 'hono/jsx'

// 计算开销大
const ExpensiveComponent: FC<{ data: string[] }> = ({ data }) => {
  const processed = data.map(item => item.toUpperCase()).join(', ')
  return <div>{processed}</div>
}

// 记忆化结果
const MemoizedExpensive = memo(ExpensiveComponent)

// 如果数据相同，则不会重新计算
<MemoizedExpensive data={['a', 'b', 'c']} />

const TodoList: FC<{ todos: Todo[] }> = ({ todos }) => {
  return (
    <ul id="todo-list">
      {todos.map(todo => (
        <li key={todo.id}>
          <span>{todo.text}</span>
          <button
            hx-delete={`/todos/${todo.id}`}
            hx-target="closest li"
            hx-swap="outerHTML"
          >
            Delete
          </button>
        </li>
      ))}
    </ul>
  )
}

app.get('/todos', async (c) => {
  const todos = await getTodos()

  return c.html(
    <Layout title="Todos">
      <script src="https://unpkg.com/htmx.org@1.9.10"></script>
      <h1>Todos</h1>
      <TodoList todos={todos} />
      <form hx-post="/todos" hx-target="#todo-list" hx-swap="beforeend">
        <input name="text" placeholder="New todo" />
        <button type="submit">Add</button>
      </form>
    </Layout>
  )
})

app.post('/todos', async (c) => {
  const { text } = await c.req.parseBody()
  const todo = await createTodo(text as string)

  return c.html(
    <li>
      <span>{todo.text}</span>
      <button
        hx-delete={`/todos/${todo.id}`}
        hx-target="closest li"
        hx-swap="outerHTML"
      >
        Delete
      </button>
    </li>
  )
})

与 Tailwind CSS 集成

const Button: FC<{ variant: 'primary' | 'secondary' }> = ({ variant, children }) => {
  const baseClasses = 'px-4 py-2 rounded font-medium transition-colors'
  const variantClasses = variant === 'primary'
    ? 'bg-blue-600 text-white hover:bg-blue-700'
    : 'bg-gray-200 text-gray-800 hover:bg-gray-300'

  return (
    <button class={`${baseClasses} ${variantClasses}`}>
      {children}
    </button>
  )
}

import type { FC, PropsWithChildren } from 'hono/jsx'
import { Fragment, createContext, useContext, memo } from 'hono/jsx'
import { Suspense, renderToReadableStream } from 'hono/jsx/streaming'
import { ErrorBoundary } from 'hono/jsx'
import { raw } from 'hono/html'

// 直接渲染
c.html(<Component />)

// 流式传输
c.body(renderToReadableStream(<Component />), {
  headers: { 'Content-Type': 'text/html; charset=UTF-8' }
})

// 基础
const Comp: FC = () => <div>Hello</div>

// 带 props
const Comp: FC<{ name: string }> = ({ name }) => <div>{name}</div>

// 带 children
const Comp: FC<PropsWithChildren> = ({ children }) => <div>{children}</div>

// 异步
const Comp: FC = async () => {
  const data = await fetch()
  return <div>{data}</div>
}

hono-core - 框架基础
hono-middleware - 中间件模式
hono-cloudflare - 边缘部署

版本 : Hono 4.x 最后更新 : 2025年1月 许可证 : MIT

🇺🇸English

Hono JSX - Server-Side Rendering

Overview

Hono provides a built-in JSX renderer for server-side HTML generation. It supports async components, streaming with Suspense, and integrates seamlessly with Hono's response system.

Key Features :

Server-side JSX rendering
Async component support
Streaming with Suspense
Automatic head hoisting
Error boundaries
Context API
Zero client-side hydration overhead

When to Use This Skill

Use Hono JSX when:

Building server-rendered HTML pages
Creating email templates
Generating static HTML
Streaming large HTML responses
Building MPA (Multi-Page Applications)

Not for : Interactive SPAs (use React/Vue/Svelte instead)

Configuration

TypeScript Configuration

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx"
  }
}

Alternative: Pragma Comments

/** @jsx jsx */
/** @jsxImportSource hono/jsx */

Deno Configuration

// deno.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "npm:hono/jsx"
  }
}

Basic Usage

Simple Rendering

import { Hono } from 'hono'

const app = new Hono()

app.get('/', (c) => {
  return c.html(
    <html>
      <head>
        <title>Hello Hono</title>
      </head>
      <body>
        <h1>Hello, World!</h1>
      </body>
    </html>
  )
})

Components

import { Hono } from 'hono'
import type { FC } from 'hono/jsx'

// Define props type
type GreetingProps = {
  name: string
  age?: number
}

// Functional component
const Greeting: FC<GreetingProps> = ({ name, age }) => {
  return (
    <div>
      <h1>Hello, {name}!</h1>
      {age && <p>You are {age} years old.</p>}
    </div>
  )
}

const app = new Hono()

app.get('/hello/:name', (c) => {
  const name = c.req.param('name')
  return c.html(<Greeting name={name} />)
})

Layout Components

import type { FC, PropsWithChildren } from 'hono/jsx'

const Layout: FC<PropsWithChildren<{ title: string }>> = ({ title, children }) => {
  return (
    <html>
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>{title}</title>
        <link rel="stylesheet" href="/styles.css" />
      </head>
      <body>
        <header>
          <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
          </nav>
        </header>
        <main>{children}</main>
        <footer>
          <p>&copy; 2025 My App</p>
        </footer>
      </body>
    </html>
  )
}

app.get('/', (c) => {
  return c.html(
    <Layout title="Home">
      <h1>Welcome!</h1>
      <p>This is my home page.</p>
    </Layout>
  )
})

Async Components

Basic Async

const AsyncUserList: FC = async () => {
  const users = await fetchUsers()

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  )
}

app.get('/users', async (c) => {
  return c.html(<AsyncUserList />)
})

Nested Async Components

const UserProfile: FC<{ id: string }> = async ({ id }) => {
  const user = await fetchUser(id)

  return (
    <div class="profile">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <UserPosts userId={id} />
    </div>
  )
}

const UserPosts: FC<{ userId: string }> = async ({ userId }) => {
  const posts = await fetchUserPosts(userId)

  return (
    <div class="posts">
      <h3>Posts</h3>
      {posts.map(post => (
        <article key={post.id}>
          <h4>{post.title}</h4>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  )
}

Streaming with Suspense

Basic Streaming

import { Suspense, renderToReadableStream } from 'hono/jsx/streaming'

const SlowComponent: FC = async () => {
  await new Promise(resolve => setTimeout(resolve, 2000))
  return <div>Loaded after 2 seconds!</div>
}

app.get('/stream', (c) => {
  const stream = renderToReadableStream(
    <html>
      <body>
        <h1>Streaming Demo</h1>
        <Suspense fallback={<div>Loading...</div>}>
          <SlowComponent />
        </Suspense>
      </body>
    </html>
  )

  return c.body(stream, {
    headers: {
      'Content-Type': 'text/html; charset=UTF-8',
      'Transfer-Encoding': 'chunked'
    }
  })
})

Multiple Suspense Boundaries

const Page: FC = () => {
  return (
    <Layout title="Dashboard">
      <h1>Dashboard</h1>

      <Suspense fallback={<div>Loading user...</div>}>
        <UserProfile />
      </Suspense>

      <Suspense fallback={<div>Loading stats...</div>}>
        <Statistics />
      </Suspense>

      <Suspense fallback={<div>Loading feed...</div>}>
        <ActivityFeed />
      </Suspense>
    </Layout>
  )
}

Error Boundaries

import { ErrorBoundary } from 'hono/jsx'

const RiskyComponent: FC = () => {
  if (Math.random() > 0.5) {
    throw new Error('Random error!')
  }
  return <div>Success!</div>
}

const ErrorFallback: FC<{ error: Error }> = ({ error }) => {
  return (
    <div class="error">
      <h3>Something went wrong</h3>
      <p>{error.message}</p>
    </div>
  )
}

app.get('/risky', (c) => {
  return c.html(
    <Layout title="Risky Page">
      <ErrorBoundary fallback={ErrorFallback}>
        <RiskyComponent />
      </ErrorBoundary>
    </Layout>
  )
})

Async Error Boundaries

const AsyncRiskyComponent: FC = async () => {
  const data = await fetchData()

  if (!data) {
    throw new Error('Data not found')
  }

  return <div>{data}</div>
}

// Error boundary catches async errors too
<ErrorBoundary fallback={({ error }) => <p>Error: {error.message}</p>}>
  <AsyncRiskyComponent />
</ErrorBoundary>

Context API

Creating Context

import { createContext, useContext } from 'hono/jsx'

type Theme = 'light' | 'dark'

const ThemeContext = createContext<Theme>('light')

const ThemedButton: FC<{ label: string }> = ({ label }) => {
  const theme = useContext(ThemeContext)
  const className = theme === 'dark' ? 'btn-dark' : 'btn-light'

  return <button class={className}>{label}</button>
}

const App: FC<{ theme: Theme }> = ({ theme, children }) => {
  return (
    <ThemeContext.Provider value={theme}>
      <div class={`app theme-${theme}`}>
        {children}
      </div>
    </ThemeContext.Provider>
  )
}

app.get('/', (c) => {
  const theme = c.req.query('theme') as Theme || 'light'

  return c.html(
    <App theme={theme}>
      <ThemedButton label="Click me" />
    </App>
  )
})

Head Hoisting

Tags like <title>, <meta>, <link>, and <script> are automatically hoisted to <head>:

const Page: FC<{ title: string }> = ({ title, children }) => {
  return (
    <html>
      <head>
        {/* Base head content */}
      </head>
      <body>
        {/* These will be hoisted to head! */}
        <title>{title}</title>
        <meta name="description" content="Page description" />
        <link rel="stylesheet" href="/page.css" />

        <div>{children}</div>
      </body>
    </html>
  )
}

// Even from nested components
const SEO: FC<{ title: string; description: string }> = ({ title, description }) => {
  return (
    <>
      <title>{title}</title>
      <meta name="description" content={description} />
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
    </>
  )
}

const Article: FC<{ article: Article }> = ({ article }) => {
  return (
    <div>
      <SEO title={article.title} description={article.excerpt} />
      <h1>{article.title}</h1>
      <div>{article.content}</div>
    </div>
  )
}

Raw HTML

dangerouslySetInnerHTML

const RawHtml: FC<{ html: string }> = ({ html }) => {
  return <div dangerouslySetInnerHTML={{ __html: html }} />
}

// Usage
const markdown = await renderMarkdown(content)
<RawHtml html={markdown} />

Raw Helper

import { raw } from 'hono/html'

const Page: FC = () => {
  return (
    <html>
      <body>
        {raw('<script>console.log("Hello")</script>')}
      </body>
    </html>
  )
}

Fragments

import { Fragment } from 'hono/jsx'

// Using Fragment
const List: FC = () => {
  return (
    <Fragment>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </Fragment>
  )
}

// Using short syntax
const List2: FC = () => {
  return (
    <>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
    </>
  )
}

Memoization

import { memo } from 'hono/jsx'

// Expensive to compute
const ExpensiveComponent: FC<{ data: string[] }> = ({ data }) => {
  const processed = data.map(item => item.toUpperCase()).join(', ')
  return <div>{processed}</div>
}

// Memoize the result
const MemoizedExpensive = memo(ExpensiveComponent)

// Won't recompute if data is the same
<MemoizedExpensive data={['a', 'b', 'c']} />

Integration Patterns

With HTMX

const TodoList: FC<{ todos: Todo[] }> = ({ todos }) => {
  return (
    <ul id="todo-list">
      {todos.map(todo => (
        <li key={todo.id}>
          <span>{todo.text}</span>
          <button
            hx-delete={`/todos/${todo.id}`}
            hx-target="closest li"
            hx-swap="outerHTML"
          >
            Delete
          </button>
        </li>
      ))}
    </ul>
  )
}

app.get('/todos', async (c) => {
  const todos = await getTodos()

  return c.html(
    <Layout title="Todos">
      <script src="https://unpkg.com/htmx.org@1.9.10"></script>
      <h1>Todos</h1>
      <TodoList todos={todos} />
      <form hx-post="/todos" hx-target="#todo-list" hx-swap="beforeend">
        <input name="text" placeholder="New todo" />
        <button type="submit">Add</button>
      </form>
    </Layout>
  )
})

app.post('/todos', async (c) => {
  const { text } = await c.req.parseBody()
  const todo = await createTodo(text as string)

  return c.html(
    <li>
      <span>{todo.text}</span>
      <button
        hx-delete={`/todos/${todo.id}`}
        hx-target="closest li"
        hx-swap="outerHTML"
      >
        Delete
      </button>
    </li>
  )
})

With Tailwind CSS

const Button: FC<{ variant: 'primary' | 'secondary' }> = ({ variant, children }) => {
  const baseClasses = 'px-4 py-2 rounded font-medium transition-colors'
  const variantClasses = variant === 'primary'
    ? 'bg-blue-600 text-white hover:bg-blue-700'
    : 'bg-gray-200 text-gray-800 hover:bg-gray-300'

  return (
    <button class={`${baseClasses} ${variantClasses}`}>
      {children}
    </button>
  )
}

Quick Reference

Key Imports

import type { FC, PropsWithChildren } from 'hono/jsx'
import { Fragment, createContext, useContext, memo } from 'hono/jsx'
import { Suspense, renderToReadableStream } from 'hono/jsx/streaming'
import { ErrorBoundary } from 'hono/jsx'
import { raw } from 'hono/html'

Response Methods

// Direct render
c.html(<Component />)

// Streaming
c.body(renderToReadableStream(<Component />), {
  headers: { 'Content-Type': 'text/html; charset=UTF-8' }
})

Component Types

// Basic
const Comp: FC = () => <div>Hello</div>

// With props
const Comp: FC<{ name: string }> = ({ name }) => <div>{name}</div>

// With children
const Comp: FC<PropsWithChildren> = ({ children }) => <div>{children}</div>

// Async
const Comp: FC = async () => {
  const data = await fetch()
  return <div>{data}</div>
}

Related Skills

hono-core - Framework fundamentals
hono-middleware - Middleware patterns
hono-cloudflare - Edge deployment

Version : Hono 4.x Last Updated : January 2025 License : MIT

Weekly Installs

Repository

bobmatnyc/claud…m-skills

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli59

opencode59

codex59

github-copilot58

claude-code53

cursor53

Genkit JS 开发指南：AI 应用构建、错误排查与最佳实践

7,700 周安装

Hono JSX 服务端渲染指南：异步组件、流式传输与 HTML 生成

🇨🇳中文介绍

Hono JSX - 服务端渲染

概述

何时使用此技能

配置

TypeScript 配置

替代方案：编译指示注释

Deno 配置

相关 Skills

基本用法

简单渲染

组件

布局组件

异步组件

基本异步

嵌套异步组件

使用 Suspense 进行流式传输

基本流式传输

多个 Suspense 边界

错误边界

异步错误边界

上下文 API

创建上下文

头部提升

原始 HTML

dangerouslySetInnerHTML

Raw 辅助函数

片段

记忆化

集成模式

与 HTMX 集成

与 Tailwind CSS 集成

快速参考

关键导入

响应方法

组件类型

相关技能

🇺🇸English

Hono JSX - Server-Side Rendering

Overview

When to Use This Skill

Configuration

TypeScript Configuration

Alternative: Pragma Comments

Deno Configuration

Basic Usage

Simple Rendering

Components

Layout Components

Async Components

Basic Async

Nested Async Components

Streaming with Suspense

Basic Streaming

Multiple Suspense Boundaries

Error Boundaries

Async Error Boundaries

Context API

Creating Context

Head Hoisting

Raw HTML

dangerouslySetInnerHTML

Raw Helper

Fragments

Memoization

Integration Patterns

With HTMX

With Tailwind CSS

Quick Reference

Key Imports

Response Methods

Component Types

Related Skills

最新 Skills