cloudwerk-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudwerk Configuration

Cloudwerk 配置参考

Reference for

cloudwerk.config.ts

— the main configuration file for Cloudwerk applications.

cloudwerk.config.ts

参考文档 —— Cloudwerk 应用的核心配置文件。

When to Apply

适用场景

Reference these guidelines when:

Creating a new Cloudwerk project
Choosing between hono-jsx and react renderers
Configuring Vite plugins (Tailwind CSS, etc.)
Setting up path aliases
Troubleshooting build or rendering issues

参考本文档的场景包括：

创建新的 Cloudwerk 项目
在 hono-jsx 和 react 渲染器之间做选择
配置 Vite 插件（如 Tailwind CSS 等）
设置路径别名
排查构建或渲染问题

Configuration File

配置文件

Every Cloudwerk app has a

cloudwerk.config.ts

at the project root:

typescript

import { defineConfig } from '@cloudwerk/core'

export default defineConfig({
  // Configuration options here
})

每个 Cloudwerk 应用的项目根目录下都有一个

cloudwerk.config.ts

文件：

typescript

import { defineConfig } from '@cloudwerk/core'

export default defineConfig({
  // Configuration options here
})

Renderer Selection

渲染器选择

hono-jsx (Default)

hono-jsx（默认）

Lightweight server-side rendering using Hono's built-in JSX. No client-side hydration or React hooks.

typescript

import { defineConfig } from '@cloudwerk/core'
import tailwindcss from '@tailwindcss/vite'
import { fileURLToPath } from 'url'
import { dirname, resolve } from 'path'

const __dirname = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  ui: {
    renderer: 'hono-jsx',
  },
  vite: {
    plugins: [tailwindcss()],
    resolve: {
      alias: {
        '@': resolve(__dirname, './'),
      },
    },
  },
})

Use hono-jsx when:

Building server-rendered pages without client interactivity
Minimizing bundle size
Building API-heavy applications with minimal UI

JSX differences with hono-jsx:

Use
```
class
```
instead of
```
className
```
Use
```
for
```
instead of
```
htmlFor
```
No React hooks (
```
useState
```
,
```
useEffect
```
, etc.)
No
```
'use client'
```
directive support

使用 Hono 内置的 JSX 实现轻量级服务端渲染。无需客户端水合或 React 钩子。

typescript

import { defineConfig } from '@cloudwerk/core'
import tailwindcss from '@tailwindcss/vite'
import { fileURLToPath } from 'url'
import { dirname, resolve } from 'path'

const __dirname = dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  ui: {
    renderer: 'hono-jsx',
  },
  vite: {
    plugins: [tailwindcss()],
    resolve: {
      alias: {
        '@': resolve(__dirname, './'),
      },
    },
  },
})

推荐使用 hono-jsx 的场景：

构建无客户端交互的服务端渲染页面
最小化打包体积
构建以 API 为主、UI 极简的应用

hono-jsx 的 JSX 语法差异：

使用
```
class
```
而非
```
className
```
使用
```
for
```
而非
```
htmlFor
```
不支持 React 钩子（
```
useState
```
、
```
useEffect
```
等）
不支持
```
'use client'
```
指令

react

Full React SSR with hydration support. Enables client components, React hooks, and interactive UIs.

typescript

import { defineConfig } from '@cloudwerk/core'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  ui: {
    renderer: 'react',
  },
  vite: {
    plugins: [tailwindcss()],
  },
})

Use react when:

Building interactive UIs with client-side state
Using React hooks (
```
useState
```
,
```
useEffect
```
,
```
useRef
```
)
Need
```
'use client'
```
components
Using React component libraries

JSX conventions with react:

Use
```
className
```
instead of
```
class
```
Use
```
htmlFor
```
instead of
```
for
```
Full React hooks support
```
'use client'
```
directive for client components

完整的 React 服务端渲染，支持水合。可启用客户端组件、React 钩子和交互式 UI。

typescript

import { defineConfig } from '@cloudwerk/core'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  ui: {
    renderer: 'react',
  },
  vite: {
    plugins: [tailwindcss()],
  },
})

推荐使用 react 的场景：

构建带有客户端状态的交互式 UI
使用 React 钩子（
```
useState
```
、
```
useEffect
```
、
```
useRef
```
）
需要
```
'use client'
```
组件
使用 React 组件库

react 的 JSX 语法规范：

使用
```
className
```
而非
```
class
```
使用
```
htmlFor
```
而非
```
for
```
完全支持 React 钩子
为客户端组件使用
```
'use client'
```
指令

Vite Configuration

Vite 配置

The

vite

key accepts any Vite configuration:

typescript

export default defineConfig({
  vite: {
    // Vite plugins
    plugins: [tailwindcss()],

    // Path aliases
    resolve: {
      alias: {
        '@': resolve(__dirname, './'),
        '@components': resolve(__dirname, './app/components'),
      },
    },

    // Build options
    build: {
      sourcemap: true,
    },
  },
})

vite

配置项支持所有 Vite 配置参数：

typescript

export default defineConfig({
  vite: {
    // Vite plugins
    plugins: [tailwindcss()],

    // Path aliases
    resolve: {
      alias: {
        '@': resolve(__dirname, './'),
        '@components': resolve(__dirname, './app/components'),
      },
    },

    // Build options
    build: {
      sourcemap: true,
    },
  },
})

Quick Comparison

快速对比

Feature	hono-jsx	react
CSS classes	`class`	`className`
Client components	No	Yes ( `'use client'` )
React hooks	No	Yes
Bundle size	Smaller	Larger
Hydration	No	Yes
Best for	Content sites, APIs	Interactive apps

特性	hono-jsx	react
CSS 类名	`class`	`className`
客户端组件	不支持	支持（通过 `'use client'` ）
React 钩子	不支持	支持
打包体积	更小	更大
水合机制	无	有
最佳适用场景	内容站点、API 服务	交互式应用