如何5分钟用Farm.js搭建全栈Web应用:新手从创建项目到跑通开发的完整教程

原创2026-11-03 17:46:501,712 阅读

如何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

这条命令做了三件事:

  1. 调用官方脚手架 @farm.js/create-app 生成项目骨架;
  2. --template basic 选择最精简的基础模板,React 是默认渲染器;
  3. --typescript 开启 TypeScript 支持,并自动安装好 React 等全部启动依赖。

想要看看还有哪些现成模板(认证、AI、Stripe 等),加上参数即可列出完整清单:

pnpm create @farm.js/app --list-templates

Farm.js v0.1.0 全栈Web框架版本发布海报

理解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 这类动态路由。

Farm.js 官网首页与文档入口的桌面端界面

编写第一个页面: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开发后的学习路径与资源

到这里,你已完成 Farm.js 完整上手流程:创建项目 → 认识目录 → 编写页面 → 跑通开发服务器,全程约 5 分钟。接下来建议按顺序深入:

想直接研究框架源码,可以克隆仓库后浏览各 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! 换成你自己的第一行内容吧 🚀

登录后查看全文
farm.js