如何5分钟用Farm.js搭建全栈Web应用:新手从创建项目到跑通开发的完整教程
如何5分钟用Farm.js搭建全栈Web应用:新手从创建项目到跑通开发的完整教程
Farm.js 是一个基于 Vite 构建的全栈 Web 框架,面向现代 React 应用与 AI Agent 场景,内置 React Server Components、流式 SSR、类型化文件路由与 Server Actions。本文面向新手,用 5 分钟带你完成 Farm.js 教程的完整流程:创建项目、认识目录结构、编写第一个页面,并跑通开发服务器。
环境准备:一键安装前的两个前置条件
开始 Farm.js 快速上手之前,请确认本地环境满足以下两项:
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | 22.13+ | 首个原生暴露 node:sqlite 模块的 22 版本 |
| pnpm | 8+ | 项目脚手架与依赖管理工具 |
💡 版本不满足时,建议先升级 Node.js 再开始 Farm.js 项目搭建,可以避免脚手架安装阶段的隐性报错。
5分钟创建Farm.js项目:一条命令生成完整全栈应用
打开终端,执行下面这条命令,即可在当前目录生成一个名为 my-app 的 Farm.js 项目:
pnpm create @farm.js/app my-app --template basic --typescript
这条命令做了三件事:
- 调用官方脚手架
@farm.js/create-app生成项目骨架; --template basic选择最精简的基础模板,React 是默认渲染器;--typescript开启 TypeScript 支持,并自动安装好 React 等全部启动依赖。
想要看看还有哪些现成模板(认证、AI、Stripe 等),加上参数即可列出完整清单:
pnpm create @farm.js/app --list-templates
理解Farm.js项目结构:app目录与类型化路由
进入项目后,整个应用代码都集中在 src/ 目录下,约定式文件结构一目了然:
my-app/
├── src/
│ └── app/
│ ├── layout.tsx # 根布局:所有页面共享的 html/body 外壳
│ └── page.tsx # 首页(对应路由 /)
├── farm.config.ts # 框架配置文件(部署目标、重定向、请求头等)
└── package.json
几个关键约定:
src/app/是应用根目录,文件名即路由;layout.tsx包裹该层级下所有页面,适合放全局导航与页脚;- 新建子目录加
page.tsx就是新页面,例如src/app/about/page.tsx对应/about,src/app/users/[id]/page.tsx对应/users/123这类动态路由。
编写第一个页面:page.tsx 与路由约定
打开 src/app/page.tsx,它直接对应首页。React 是默认渲染器,页面里可以直接使用 JSX,模板已预配置 Tailwind CSS,样式类名随手可用:
export default function HomePage() {
return (
<div className="min-h-screen flex items-center justify-center">
<h1 className="text-5xl font-bold text-blue-600">Hello from Farm.js!</h1>
</div>
);
}
如果需要共享布局,在 src/app/layout.tsx 中导出一个包裹 children 的组件即可,框架会自动把每个页面注入其中。
启动Farm.js开发服务器:pnpm dev 跑通第一个页面
在项目根目录执行:
pnpm dev
看到终端输出后,浏览器打开 http://localhost:3000,你就能看到刚才编写的第一页。开发体验由 Vite 驱动:秒级冷启动、按需编译、热更新(HMR)——保存 page.tsx 的任何改动,浏览器即时刷新,无需手动操作。
如果是在已有项目中手动接入 Farm.js,只需安装核心包并用 npx farm dev 启动:
npm install @farm.js/core react react-dom
npx farm dev
从页面到全栈:服务端组件与API路由
Farm.js 是全栈框架,前端组件、服务端逻辑、API 接口都写在同一个项目里。
服务端组件(RSC):在 src/app/ 的组件文件中直接写 async 组件,代码运行在服务端,可以安全地读取数据库与文件系统,再把结果流式渲染成 HTML:
export default async function ProfilePage() {
const post = await getPostFromDatabase('demo');
return <article><h1>{post.title}</h1></article>;
}
API 路由:把服务端接口放在 src/app/api/ 目录下,文件即端点。页面组件与服务端函数共享同一套类型化路由,请求参数自动带类型。
跑通Farm.js开发后的学习路径与资源
到这里,你已完成 Farm.js 完整上手流程:创建项目 → 认识目录 → 编写页面 → 跑通开发服务器,全程约 5 分钟。接下来建议按顺序深入:
- 📘 官方入门文档:getting-started/page.md
- 🧩 完整示例应用(路由、边界、API 路由、渲染模式一网打尽):examples/basic
- 🗂️ 配置文件
farm.config.ts全部选项:examples/basic/farm.config.ts - 🌐 框架架构总览:ARCHITECTURE.md
想直接研究框架源码,可以克隆仓库后浏览各 packages/farm-* 目录:
git clone https://gitcode.com/gh_mirrors/fa/farm.js
常用模板速查
| 模板 | 适用场景 |
|---|---|
basic |
从零开始的最小 Farm.js 应用 |
auth |
内置认证能力 |
ai |
AI SDK 对话应用 |
react-compiler |
实验性 React AOT 编译器体验 |
从一条命令到可交互的全栈页面,Farm.js 把"创建项目到跑通开发"的门槛压到了最低。现在,去把 Hello from Farm.js! 换成你自己的第一行内容吧 🚀

