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 '@gio.js/react'`
Image JSX	`<Image src=... />`	`<GioImage src=... />`
Link component	`import Link from 'next/link'`	`import { GioLink } from '@gio.js/react'`
Link JSX	`<Link href=...>`	`<GioLink href=...>`
Navigation hooks	`from 'next/navigation'`	TODO comment added - no GioJS equivalent yet, import left intact
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 converted to [[images.remote_patterns]] sections. Redirects and rewrites are not supported by GioJS yet - they are written into gio.toml as comments so nothing is silently ignored; handle them in your reverse proxy or in getServerSideProps. 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 - declarative redirects, rewrites, headers, and cookie guards move to middleware.ts (defineMiddleware from @gio.js/core) or gio.toml, and run in the Rust layer before routing - see the Middleware page. Imperative request interception belongs in a Node plugin (GioNodePlugin with an onRequest hook)
next/navigation hooks - flagged with a TODO comment. Use GioLink for links and the browser location/history APIs for imperative navigation
Route Handlers (route.ts) - supported, no changes needed
Server Actions - not yet supported (see Known Issues)

After running the codemod, run tsc --noEmit and check for type errors. The codemod is conservative - it only transforms patterns it can identify with certainty.