#前端总览

#目录导航

• 当前能力
• Vext Frontend 是什么
• 创建全栈项目
• 项目结构
• 第一个页面
• 阅读路径

#当前能力

本前端指南描述 Vext 当前内置前端能力：route 驱动 React 19 页面、SSR、hydration、嵌套 layout、前端多语言、Fast Refresh、render refresh、代码拆分、静态资源、CDN 上传、性能预算和 hydration 验证。

#Vext Frontend 是什么

Vext Frontend 是 Vext 内置的 React 19 全栈页面能力。URL 入口仍然由 src/routes/** 定义；route handler 准备服务端数据后，通过 res.render() 渲染 src/frontend/pages/** 中的页面。

当你希望一个 Vext 项目同时拥有 API routes、services、SSR、hydration、前端资源构建和生产静态服务时，使用默认前端能力即可。

纯 API 项目使用 --template api --frontend none。

#创建全栈项目

npx vextjs create my-app
cd my-app
npm run dev

默认脚手架就是全栈 React 项目。需要纯 API 项目时：

npx vextjs create my-api --template api --frontend none

#项目结构

src/
  routes/
    index.ts
    admin/
      dashboard.ts
  services/
    user.service.ts
  frontend/
    pages/
      index.tsx
      layout.tsx
      error/
        default.tsx
    components/
      UserCard.tsx
    styles/
      card.style.ts
      dashboard.module.css
    assets/
      logo.png
    locales/
      en-US.ts
      zh-CN.ts
public/
  favicon.svg

关键边界是物理目录：

• src/routes/** 和 src/services/** 运行在服务端。
• src/frontend/pages/** 和 src/frontend/components/** 会进入浏览器构建。
• 不要在前端文件中 import services、数据库客户端、密钥或 Node-only 模块。
• public/** 会复制到前端输出目录，也会进入 deploy manifest。

#第一个页面

创建页面：

// src/frontend/pages/index.tsx
export default function HomePage(props: { greeting: string }) {
  return <main>{props.greeting}</main>;
}

在 route 中渲染：

// src/routes/index.ts
export default (app) => {
  app.get("/", {}, async (req, res) => {
    const greeting = await app.services.example.greeting("Vext");
    res.render("index", { greeting });
  });
};

res.render(page, props?, options?) 三个参数含义如下：

#阅读路径

左侧导航就是主地图，按概念、任务和参考三层组织。

旧 前端集成页 只作为历史链接兼容入口保留。