Active-tachometer477/dark
GitHub: Active-tachometer477/dark
一个结合 Go 后端和 Preact/React 前端的 SSR Web 框架，通过 Islands 架构和 htmx 实现高性能的服务端渲染与交互式页面。
Stars: 0 | Forks: 0
# Dark
一个由 [Preact](https://preactjs.com/) 或 [React](https://react.dev/)、[htmx](https://htmx.org/) 以及 Islands 架构驱动的 Go SSR Web 框架。
Dark 使用 [ramune](https://github.com/i2y/ramune)（一个专为 Go 打造的 JS/TS 运行时）在服务器上渲染 TSX 组件，通过 Go 的 Loader/Action 函数获取数据，并借助 htmx 的 HTML-over-the-wire 方案结合最少的客户端 JavaScript 来交付交互式页面。
## 环境要求
Dark 使用 ramune 进行 SSR，该运行时支持两种 JS 引擎后端：
| | JSC (默认) | QuickJS-NG (`-tags qjswasm`) |
|---|---|---|
| **引擎** | 通过 [purego](https://github.com/ebitengine/purego) 调用 Apple JavaScriptCore | 编译为 WebAssembly 的 QuickJS-NG，由 [wazero](https://github.com/tetratelabs/wazero)（纯 Go）驱动 |
| **JIT** | 是 | wazero 编译器模式 (AOT WASM→本地代码) |
| **平台** | macOS, Linux | macOS, Linux, Windows, FreeBSD |
| **系统依赖** | macOS: 无。Linux: `apt install libjavascriptcoregtk-4.1-dev` | 无 |
| **适用场景** | 生产环境性能 | 可移植性，零依赖部署 |
两者都是纯 Go 构建——无需 C 编译器或 Cgo。
### 默认引擎
```
# macOS — 无额外依赖
go build .
# Linux
sudo apt install libjavascriptcoregtk-4.1-dev
go build .
```
### QuickJS-NG 后端
```
go build -tags qjswasm .
```
无需共享库。在包括 Windows 的所有平台上均可运行。权衡之处：比 JSC 的 JIT 慢，但 wazero 编译器模式的 AOT 路径大幅缩小了差距。对于大多数瓶颈在 I/O（数据库、网络）的应用来说，差异微乎其微。
## 基于 net/http 构建
Dark 遵循标准的 `net/http` 约定。没有任何外部路由依赖。
- 内部路由使用 `http.NewServeMux` 及 Go 1.22+ 增强的路由模式 (`GET /users/{id}`)
- `app.Handler()` 返回 `(http.Handler, error)` —— 可将其插入任何 Go HTTP 技术栈
- 中间件采用标准的 `func(http.Handler) http.Handler` 签名
- Dark 不控制服务器 —— 你可以使用 `http.ListenAndServe` 或 `http.Server` 自行启动
```
// Simple — MustHandler() panics on error (convenient for main)
http.ListenAndServe(":3000", app.MustHandler())
// With error handling
handler, err := app.Handler()
if err != nil {
log.Fatal(err)
}
http.ListenAndServe(":3000", handler)
// With http.Server for full control
srv := &http.Server{
Addr: ":8080",
Handler: app.MustHandler(),
ReadTimeout: 5 * time.Second,
WriteTimeout: 10 * time.Second,
}
srv.ListenAndServe()
```
任何现有的 `net/http` 中间件均可通过 `app.Use()` 开箱即用。
## 功能特性
- **服务端渲染** —— 通过 Preact 或 React 的 `renderToString` 在沙箱化的 JS 运行时中渲染 TSX 模板
- **Loader/Action 模式** —— 使用 Go 函数进行数据获取和修改，props 以 JSON 格式传递
- **htmx 集成** —— 感知 HX-Request 的响应（完整页面 vs HTML 片段）
- **Islands 架构** —— 结合懒加载（`load`、`idle`、`visible`）进行选择性客户端注水
- **流式 SSR** —— shell-first 渲染，提供更快的 TTFB
- **嵌套布局** —— 通过路由分组实现可组合的布局
- **表单验证** —— 字段级错误提示及表单数据保留
- **会话管理** —— HMAC 签名的 Cookie 会话及 Flash 消息
- **身份验证** —— 带有 htmx 感知重定向的 `RequireAuth` 中间件
- **Head 标签管理** —— 针对每个页面的 ``、`<meta>` 和 OpenGraph 标签
- **API 路由** —— 与页面路由并存的 JSON 端点
- **开发模式** —— 热重载、带有 Source Map 的错误提示覆盖层、TypeScript 类型生成
- **SSR 缓存** —— 带有 ETag / 304 Not Modified 的 LRU 内存缓存
- **CSRF 防护** —— 基于会话的 Token，自动与 htmx/TSX 集成
- **并发 Loaders** —— 并行获取数据并合并结果
- **内嵌视图** —— 从 `embed.FS` 加载 TSX 文件以实现单二进制文件部署
- **静态文件系统** —— 从任何 `fs.FS` (embed.FS, os.DirFS) 提供静态资源服务
- **JSX 自动转换** —— 无需 `import { h }` 或 `import React` 等样板代码
- **桌面应用** —— 通过 WebView 创建原生窗口，具备 Go↔JS 绑定和双向事件通信
## 快速开始
```
package main
import (
"log"
"net/http"
"github.com/i2y/dark"
)
func main() {
app, err := dark.New(
dark.WithLayout("layouts/default.tsx"),
dark.WithTemplateDir("views"),
dark.WithDevMode(true),
)
if err != nil {
log.Fatal(err)
}
defer app.Close()
app.Use(dark.Logger())
app.Use(dark.Recover())
app.Get("/", dark.Route{
Component: "pages/index.tsx",
Loader: func(ctx dark.Context) (any, error) {
return map[string]any{"message": "Hello, Dark!"}, nil
},
})
log.Fatal(http.ListenAndServe(":3000", app.MustHandler()))
}
```
布局包裹了每一个页面。每个页面组件的输出都作为 `children` 传递。在处理 htmx 请求（`HX-Request` 请求头）时，会跳过布局并仅返回页面片段。
```
// views/layouts/default.tsx
export default function Layout({ children }) {
return (
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>My App
{children}