Migration Guide

Migrate a Next.js app to GioJS in minutes using the gio-migrate codemod CLI.

Automatic migration

Run the codemod from your project root:

bash

npx gio-migrate .

The codemod scans all .tsx/.ts/.jsx/.js files and applies transforms in-place. Use --dry-run to preview changes without writing:

bash

npx gio-migrate --dry-run .

Transforms applied

Pattern	Before	After
Client directive	`'use client'`	Removed (comment added)
Image component	`import Image from 'next/image'`	`import { GioImage } from 'giojs/react'`
Image JSX	`<Image src=... />`	`<GioImage src=... />`
Link component	`import Link from 'next/link'`	`import { GioLink } from 'giojs/react'`
Link JSX	`<Link href=...>`	`<GioLink href=...>`
Navigation hooks	`from 'next/navigation'`	`from 'giojs/navigation'`
Font imports	`from 'next/font/google'`	TODO comment added — move to `gio.toml`

Migrating next.config.js

bash

npx gio-migrate --config next.config.js

This generates gio.toml with your images.remotePatterns, redirects, and rewrites converted. A migration-report.md lists anything that needs manual attention (custom webpack config, headers, experimental flags).

What requires manual migration

next/font — declare fonts in gio.toml [[fonts]] section instead of importing from next/font
Middleware — GioJS compiles middleware rules to Rust at build time. Define rules in middleware.ts and run gio build
Route Handlers (route.ts) — supported, no changes needed
Server Actions — not yet supported (see Known Issues)

After running the codemod, run npx gio build and check for type errors. The codemod is conservative — it only transforms patterns it can identify with certainty.