前端项目 (Frontend Projects)

对于具有构建步骤的应用（如 React、Vue、Svelte 等），zero-native 提供了帮助工具，用于在开发服务器与打包后的静态资源之间进行切换。

动态源函数 (Dynamic Source Function)

在你的 App 上使用 source_fn，以便在开发过程中使用本地开发服务器，在生产环境中使用打包后的静态资源：

fn source(context: *anyopaque) anyerror!zero_native.WebViewSource {
    const self: *App = @ptrCast(@alignCast(context));
    return zero_native.frontend.sourceFromEnv(self.env_map, .{
        .dist = "dist",
        .entry = "index.html",
    });
}

sourceFromEnv 会检查环境变量 ZERO_NATIVE_FRONTEND_URL。如果该变量已设置，它将返回一个 URL 源；否则，它将从 config.dist 返回一个静态资源源 (Assets source)。

frontend.Config

字段	默认值	描述
dist	"dist"	构建后的前端输出目录路径
entry	"index.html"	dist 目录内的 HTML 入口文件
origin	"zero://app"	静态资源 URL 的源（Origin）
spa_fallback	true	对未知路由返回入口文件
dev_url_env	"ZERO_NATIVE_FRONTEND_URL"	sourceFromEnv 检查的环境变量名称

在 app.zon 中进行配置

.frontend = .{
    .dist = "dist",
    .entry = "index.html",
    .spa_fallback = true,
    .dev = .{
        .url = "http://127.0.0.1:5173/",
        .command = .{ "npm", "run", "dev", "--", "--host", "127.0.0.1" },
        .ready_path = "/",
        .timeout_ms = 30000,
    },
}

开发服务器 (Dev Server)

使用 zero-native dev 命令让 zero-native 管理前端开发服务器的生命周期：

zero-native dev --binary zig-out/bin/MyApp
zero-native dev --binary zig-out/bin/MyApp --url http://127.0.0.1:3000/ --command "npm run dev"

该命令将启动前端进程，等待该端口接受连接，然后使用 ZERO_NATIVE_FRONTEND_URL 启动原生外壳（Shell）程序，最后在外壳程序退出时终止前端进程。更多参数选项，请参见开发服务器文档。

框架配置配方 (Recipes)

• Vite：.url = "http://127.0.0.1:5173/", 启动命令为 npm run dev -- --host 127.0.0.1。
• Next.js：.url = "http://127.0.0.1:3000/", 启动命令为 npm run dev -- --hostname 127.0.0.1。
• 静态预览：将 .dist 指向构建输出目录，并使用任何本地服务器启动命令。

示例项目

代码库中包含了完整的前端示例：

• examples/next — 使用了 frontend/out 生产环境静态资源的 Next.js 应用。
• examples/react — 使用 Vite 构建的 React 应用。
• examples/svelte — 使用 Vite 构建的 Svelte 应用。
• examples/vue — 使用 Vite 构建的 Vue 应用。

每个示例都可以在其目录下通过 zig build run 运行，或者使用 zig build dev 来运行受管理的前端开发服务器工作流。

生产环境源 (Production Source)

对于始终使用本地打包静态资源的发布版本：

return zero_native.frontend.productionSource(.{ .dist = "dist", .entry = "index.html" });

ZERO_NATIVE_FRONTEND_ASSETS

ZERO_NATIVE_FRONTEND_ASSETS 是一个应用自定义的约定（前端模块本身并不会读取它）。在示例中，使用它来指示应通过 productionSource 加载预构建的静态资源，而不是使用默认的“开发 / 生产”分支切换逻辑。