---
title: "Migrate from Nuxt"
description: "Move a Nuxt application to Farm by mapping Vue pages, layouts, server routes, middleware, data, and runtime configuration."
canonical_url: "https://mcp.farmjs.dev/docs/migrations/nuxt"
markdown_url: "https://mcp.farmjs.dev/docs/migrations/nuxt.md"
last_updated: "2026-10-20"
---
# Migrate from Nuxt to Farm
This document is the complete instruction set for a coding agent that has been asked to migrate a
Nuxt 3 or Nuxt 4 application to Farm while keeping its Vue Single-File Components through the
`@farm.js/vue` renderer. It contains the task contract, the ordered procedure, verification gates,
and a feature parity map that gives every Nuxt feature its Farm file convention, import path, and
status. Do the migration by hand: no Farm CLI command detects or rewrites Nuxt projects. Every Farm
API named here exists in Farm 0.1.14; when this document marks a feature `none`, do not invent a
Farm API for it, use the stated workaround.
Status values: `same` works unchanged; `rename` keeps the behavior but moves the file or changes
the import or name; `different` has a Farm equivalent with another shape, rewrite as shown; `none`
has no Farm equivalent, apply the workaround and list it in the final report.
## Task contract
**Goal.** The same URLs, API contracts, status codes, cookies, metadata, and interactive behavior,
served by Farm with Vue SFC route files.
**Prerequisites.** Node `>=22.13.0` (required by `@farm.js/vue`), pnpm, a clean git working tree,
and a record of the Nuxt app's behavior before you change it: list every page URL, every
`server/api` and `server/routes` endpoint with method and status, and every `routeRules` entry.
**Facts that apply to every migration (verified on Farm 0.1.14):**
- Farm's app directory is `src/app`. Pages are `page.vue`, layouts are `layout.vue`, one folder per
URL segment.
- Farm aliases `@/` to `src/`. Nuxt's `~/` and `@/` pointed at `app/` (Nuxt 4) or the project root
(Nuxt 3). Rewrite those imports and the tsconfig `paths`. `~/`, `~~/`, `@@/`, and `#shared` are
not defined by Farm.
- Build output is `.farm/.output`. The production start script is
`node .farm/.output/server/index.mjs`. `farm start` runs the same server but needs the
`@farm.js/cli` devDependency, so use it only locally. Never use `node .output/server/index.mjs`:
that is Nuxt's output path and will run a stale Nuxt build or fail.
- Farm passes no `configFile: false` to Vite for `farm dev` or for the production client and SSR
builds, so Vite's default lookup loads a project-root `vite.config.*`. Delete any leftover
`vite.config.*` that registers Nuxt or other framework plugins, and move options you still need
into the `vite` field of `farm.config.ts`.
- Farm loads `.env`, `.env.local`, `.env.[mode]`, and `.env.[mode].local` through Vite's `loadEnv`
when it loads `farm.config.ts`.
- Vue routes are server-rendered HTML with no client JavaScript unless the route module exports
`hydrate = true`. Vue hydrates at the route boundary: a hydrated page hydrates its whole route.
- Farm has no Vue `Link` component and does not intercept plain `` clicks. `` performs a
full document navigation. SPA navigation in Vue is `useRouter().push()` from
`@farm.js/vue/bindings`.
- Install Vue plugins (Pinia, vue-i18n, UI libraries) with an app setup module: `vue({ app:
"./src/vue-app.ts" })` in `farm.config.ts`, where the module default-exports `defineVueApp((app,
{ ssr }) => { app.use(...) })` from `@farm.js/vue`. Farm calls it for every Vue app: once per
server render and once per hydrated root. Requires Farm 0.1.22 or later. Server-side store state
is not transferred to the browser.
**Done means:** every recorded URL returns the same status and content, client navigation and
hydrated interactions work, `pnpm build` and `pnpm start` succeed, type-check passes, and no `nuxt`,
`#app`, `#imports`, `#components`, or `.nuxt` reference remains.
## Migration procedure
Run the phases in order. Do not start a phase until the previous phase's verification passes.
### Phase 1: install Farm next to Nuxt
Pin exact versions: pnpm 11+ applies `minimumReleaseAge`, which can resolve `latest` to an older
Farm release right after a publish. Keep `@farm.js/core` and `@farm.js/cli` on the same version.
If pnpm refuses a version younger than the release-age window, add that exact `package@version` to
`minimumReleaseAgeExclude` in `pnpm-workspace.yaml`. `@farm.js/vue` requires `vue@^3.5.41`.
```bash
FARM_VERSION=$(npm view @farm.js/core version)
FARM_VUE_VERSION=$(npm view @farm.js/vue version)
pnpm add @farm.js/core@$FARM_VERSION @farm.js/vue@$FARM_VUE_VERSION vue zod
pnpm add -D @farm.js/cli@$FARM_VERSION vue-tsc typescript
```
Create `farm.config.ts`:
```ts
import { defineConfig } from "@farm.js/core";
import { vue } from "@farm.js/vue";
export default defineConfig({
renderer: vue(),
deploy: { target: "node" },
});
```
Replace `tsconfig.json` (Nuxt's extends `.nuxt/tsconfig.json`, which disappears) and add
`src/env.d.ts`:
```json
{
"compilerOptions": {
"target": "ES2020",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"skipLibCheck": true,
"noEmit": true,
"isolatedModules": true,
"resolveJsonModule": true,
"allowImportingTsExtensions": true,
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
},
"include": ["src/**/*.ts", "src/**/*.vue", "farm.config.ts"]
}
```
```ts
///
declare module "*.vue" {
import type { DefineComponent } from "vue";
const component: DefineComponent, Record, unknown>;
export default component;
}
```
Set the scripts below and delete `postinstall: nuxt prepare` (installs fail once Nuxt is gone).
Add `.farm` to `.gitignore`. Delete or empty any root `vite.config.*`.
```json
"scripts": {
"dev": "farm dev", "build": "farm build", "type-check": "vue-tsc --noEmit",
"start": "node .farm/.output/server/index.mjs"
}
```
**Verify:** with the Phase 2 layout and a one-line `src/app/page.vue`, `pnpm dev` serves
`http://localhost:3000/` and writes `src/farm.d.ts`.
### Phase 2: root layout, global CSS, static assets
Merge `app.vue` and `layouts/default.vue` into `src/app/layout.vue`. Replace `` and
`` with ``. Import global CSS from the normal script block. `public/` stays.
Farm owns ``, ``, and ``; do not render them. Every page and layout needs
`defineOptions({ inheritAttrs: false })` so route props such as `path` do not fall through to the
root DOM element.
```vue
```
### Phase 3: pages, one route at a time
Create the Farm folder and `page.vue`, add explicit imports, convert `definePageMeta`, navigation,
and data APIs using the parity tables. Keep dynamic segment names identical.
**Verify each page** in `pnpm dev`: status and HTML match the Nuxt recording; the browser console
has no `Failed to resolve component` or hydration warnings.
### Phase 4: server routes, server middleware, mutations
Convert `server/api/**`, then `server/routes/**`, `server/middleware/**`, `server/plugins/**`.
**Verify** every endpoint with `curl -i` using the recorded method, body, and cookies: status,
headers, `Set-Cookie`, and body match. `farm generate` lists the routes in `src/lib/api.generated.ts`.
### Phase 5: route middleware, auth, config, modules
Convert `app/middleware`, `runtimeConfig`, `app.config.ts`, `nuxt.config.ts`, and modules.
**Verify:** protected URLs redirect when signed out; `routeRules` headers and redirects appear in
`curl -i` output.
### Phase 6: production build
Run `pnpm build` then `pnpm start`. **Verify** the Phase 3 and 4 checks against the production
server, including SPA navigation between two hydrated routes and the state that must survive it.
### Phase 7: type-check and remove Nuxt
Run `pnpm type-check`. Remove `nuxt` and every `@nuxt/*`, `@nuxtjs/*`, `@pinia/nuxt`, and `nuxt-*`
package, plus `nuxt.config.ts`, `app.config.ts`, `.nuxt/`, `.output/`, `app/`, `server/`, and Nuxt
deployment files. This search must return nothing; then rerun Phase 6:
```bash
grep -rn --include='*.vue' --include='*.ts' -e "#app" -e "#imports" -e "#components" -e "definePageMeta" -e "defineNuxt" -e "useNuxtApp" -e "useRuntimeConfig" -e "defineEventHandler" src
```
### Failure symptoms and recovery
| Symptom | Cause | Recovery |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `farm dev` loads Nuxt or unknown Vite plugins | Leftover root `vite.config.*` | Delete it; move needed options into `farm.config.ts` `vite`. |
| `ReferenceError: ref is not defined` or `definePageMeta is not defined` | Nuxt auto-import or macro left in place | Add the explicit `vue` import; delete the macro and use the Farm export. |
| `[Vue warn]: Failed to resolve component: ProductCard` | Auto-imported component | Import the SFC explicitly in `
{{ product?.name }}
```
The page lives at `src/app/(shop)/products/[id]/page.vue`, the layout at
`src/app/(shop)/layout.vue`, the guard at `src/app/(shop)/middleware.ts`. Make 404 and redirect
decisions in `middleware.ts`, not in `
```
In routes that do not hydrate, `AppLink` renders a working `` (document navigation).
## Route middleware
Canonical docs: [/docs/middleware](/docs/middleware).
| Nuxt | Farm | Status |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| named `middleware/auth.ts` + `definePageMeta` | `middleware.ts` in the protected folder or route group | `different` |
| global `middleware/*.global.ts` | `src/app/middleware.ts` or `farm.config.ts` `middleware: [{ matcher, handler }]` | `different` |
| inline middleware in `definePageMeta` | `middleware.ts` next to the page | `different` |
| `defineNuxtRouteMiddleware((to, from) => ...)` | `export async function middleware(request: Request, context: RequestMiddlewareContext)` (type from `@farm.js/core/middleware`) | `different` |
| `to.params`, `to.path`, `to.query` | `context.params`, `context.pathname`, `context.searchParams` | `rename` |
| `return navigateTo("/login")` | `return Response.redirect(new URL("/login", request.url))` or `context.redirect("/login")` | `different` |
| `return abortNavigation()` | `return new Response("Forbidden", { status: 403 })` | `different` |
| client-side-only middleware | None; Farm middleware runs on the server | `none` |
Farm middleware runs on the server, in development and production, for config entries first, then
`src/app/**/middleware.ts` from the root segment down.
```ts
// src/app/(account)/middleware.ts
import type { RequestMiddlewareContext } from "@farm.js/core/middleware";
import { notFound } from "@farm.js/core/navigation";
import { readSession } from "@/server/session";
export async function middleware(request: Request, context: RequestMiddlewareContext) {
const session = await readSession(request);
if (!session) return Response.redirect(new URL("/sign-in", request.url));
if (context.params.id === "0") notFound();
context.data.set("user.name", session.user.name);
context.set("session", session);
}
```
The handler continues automatically unless it returns a `Response`. `context.data` values are
client-safe and reach the page as `props.middleware?.data.get("user.name")`. Values from
`context.set()` stay on the server; read them with `getMiddlewareContext()` from
`@farm.js/core/middleware`. Repeat authorization in API routes. `context.cookies.set()` and
`context.headers.set()` add response cookies and headers.
## Data fetching
Canonical docs: [/docs/api-routes](/docs/api-routes), [/docs/api-client](/docs/api-client),
[/docs/server-queries](/docs/server-queries), [/docs/environment-functions](/docs/environment-functions).
| Nuxt | Farm | Status |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------- |
| `useFetch`/`useAsyncData` in a non-interactive page | `await` a server module in `
{{ error }}
Loading cart
```
Wrap server data access with `createServerOnlyFn` from `@farm.js/core/environment` so a module
imported by a route that later hydrates cannot ship its implementation to the browser.
`useServerQuery` and `useAction` from `@farm.js/vue/bindings` exist, but calling a server query or
server function from browser code requires the server-function transform (`@farm.js/plugin/rsc`
with `experimental.serverActions: true`). That path is not documented for Vue; prefer API routes
plus `apiClient`. Do not import `@farm.js/core/server-query/client` in Vue code: it imports React.
## State
| Nuxt | Farm | Status |
| ------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------- |
| `useState(key, init)` | None. Browser-only shared state: a module-level `ref` in a composable used by hydrated routes | `none` |
| server-to-client state transfer | None generic; pass client-safe values through middleware `context.data` or fetch after mount | `none` |
| Pinia via `@pinia/nuxt` | `app.use(createPinia())` in the app setup module (`vue({ app })`); stores start fresh in the browser | `different` |
| `provide`/`inject` (Vue) | `provide()` in a layout's `
```
Browser-only helpers: `createClientOnlyFn` from `@farm.js/core/environment` throws a clear error if
called during SSR.
## Auto-imports
Nuxt auto-imports are `none` in Farm. Every identifier must be imported explicitly.
| Nuxt auto-import | Farm import |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `ref`, `computed`, `reactive`, `watch`, `watchEffect`, `onMounted`, `nextTick`, `toRef(s)`, `provide`, `inject`, `defineAsyncComponent` | `import { ... } from "vue"` |
| `defineProps`, `defineEmits`, `defineOptions`, `defineModel` | Compiler macros; no import needed (`same`) |
| `app/components/**` (including `` from `components/base/Button.vue`) | `import BaseButton from "@/components/base/Button.vue"` |
| `app/composables/**`, `app/utils/**` | `import { useCart } from "@/composables/useCart"` |
| `server/utils/**` | `import { db } from "@/server/db"` |
| `shared/**` | `import { slugify } from "@/shared/slugify"` |
| `#imports`, `#app`, `#components` | Delete; import from the real module |
Find the gaps with `pnpm type-check` (`Cannot find name 'ref'`) and the browser console
(`Failed to resolve component`). Nuxt resolves nested component names by directory prefix; keep the
template name and import the file under that name.
## Head and SEO
Canonical docs: [/docs/routing](/docs/routing) (Metadata And OG Images).
| Nuxt | Farm | Status |
| -------------------------------------------- | ------------------------------------------------------------------------------------- | ----------- |
| `app.head` in `nuxt.config.ts` | `export const metadata` in `src/app/layout.vue` | `different` |
| `useHead` / `useSeoMeta` (static) | `export const metadata: Metadata` (type from `@farm.js/core`) in `
```
Production responses show a generic message; details stay in server logs. A `reset()` button needs
the boundary to hydrate.
## Plugins
Canonical docs: [/docs/plugins/client](/docs/plugins/client), [/docs/project-structure](/docs/project-structure).
| Nuxt | Farm | Status |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------- |
| `defineNuxtPlugin` calling `nuxtApp.vueApp.use(plugin)` | `app.use(plugin)` in the app setup module (`vue({ app })`) | `different` |
| `provide: { helper }` / `useNuxtApp().$helper` | Export the helper from a module and import it | `different` |
| global directives (`vueApp.directive`) | `app.directive()` in the app setup module, or register locally in `