Migration Guide

Move a Next.js app (pages or app router) to GioJS with one command, then work through a report of what needs a human.

Run the migration

Commit your work first - the migration edits files in place. From the project root:

npm create giojs@latest -- migrate            # current directory
npx create-giojs migrate ./my-next-app         # same thing, explicit directory

pnpm create giojs migrate                     # current directory
pnpm dlx create-giojs migrate ./my-next-app    # same thing, explicit directory

yarn create giojs migrate                     # current directory
yarn dlx create-giojs migrate ./my-next-app    # same thing, explicit directory

bun create giojs migrate                      # current directory
bunx create-giojs migrate ./my-next-app        # same thing, explicit directory

It prints a summary of every move and edit and asks before writing anything. Preview the full diff without touching a file, or skip the prompt (CI, scripts):

npx create-giojs migrate --dry-run   # summary + diff of every change, writes nothing
npx create-giojs migrate --yes       # apply without asking (required when there is no terminal)
npx create-giojs migrate --help

pnpm dlx create-giojs migrate --dry-run # summary + diff of every change, writes nothing
pnpm dlx create-giojs migrate        # apply without asking (required when there is no terminal)
pnpm dlx create-giojs migrate --help

yarn dlx create-giojs migrate --dry-run # summary + diff of every change, writes nothing
yarn dlx create-giojs migrate        # apply without asking (required when there is no terminal)
yarn dlx create-giojs migrate --help

bunx create-giojs migrate --dry-run  # summary + diff of every change, writes nothing
bunx create-giojs migrate            # apply without asking (required when there is no terminal)
bunx create-giojs migrate --help

The gio-migrate bin of the same package runs the same command (npx -p create-giojs gio-migrate). Afterwards:

npm install          # next is swapped for @gio.js/server + @gio.js/react
npx tsc --noEmit     # catches what the migration could not see
npm run dev

pnpm install         # next is swapped for @gio.js/server + @gio.js/react
pnpm exec tsc --noEmit # catches what the migration could not see
pnpm dev

yarn                 # next is swapped for @gio.js/server + @gio.js/react
yarn tsc --noEmit    # catches what the migration could not see
yarn dev

bun install          # next is swapped for @gio.js/server + @gio.js/react
bunx tsc --noEmit    # catches what the migration could not see
bun run dev

MIGRATION_REPORT.md

The migration writes MIGRATION_REPORT.md to the project root: every file moved, every change with its file:line, the converted configuration, and a checklist of TODOs. Each TODO is also a // TODO(gio-migrate): ... comment above the code it is about, so grep -rn "TODO(gio-migrate)" . finds them too. Nothing that needs a decision is changed silently.

pages/ → app/

GioJS uses the app router conventions (layouts, route groups, catch-alls, not-found/error/loading files), so an app router project keeps its structure (src/app/ moves to app/ - GioJS reads it from the project root). A pages router project is moved file by file, and relative imports in moved files are rewritten to match:

A file is never moved onto an existing one: it stays where it is with a TODO. Next.js middleware.ts is renamed to middleware.next.ts - GioJS loads middleware.ts as declarative rules (see Middleware) - and flagged for porting.

Next.js accepts JSX in .js files; GioJS compiles JSX only in .jsx/.tsx files, so every .js file with JSX is renamed to .jsx (pages/index.js → app/page.jsx, components/Nav.js → components/Nav.jsx) and imports that spell out the .js extension are updated. Files without JSX keep their name.

Catch-all params differ in shape: Next passes [...slug] as an array (['a', 'b']), GioJS as the '/'-joined string ('a/b') - in page props, getServerSideProps's params, useParams() and route handlers alike. Code in a catch-all route that reads them gets a TODO to use .split('/').

Code transforms

Source files are parsed with the TypeScript compiler (so JSX text, strings and comments are never mistaken for code) and edited in place - formatting and comments survive.

package.json drops next for @gio.js/server and @gio.js/react (plus @gio.js/core when the migrated code imports it; React moves to 19), its next dev/next startscripts run the GioJS server, and it gets "type": "module", like every GioJS app: GioJS loads app files as ES modules and @gio.js/react ships ES modules only, so without it every page importing @gio.js/react fails to load. That makes Node treat every .js file as an ES module, so CommonJS files (module.exports/require, such as postcss.config.js or tailwind.config.js) are renamed to .cjs, and a file mixing import/export with module.exports gets a TODO. tsconfig.json gets "jsx": "react-jsx" - "preserve" would leave JSX untransformed - loses the next plugin, and includes .gio/routes.d.ts for typed routes.

next.config → gio.toml

The config is read statically (it is never executed). Redirects, rewrites and headers become the gio.toml rules the Rust server evaluates before routing, with the path syntax converted: :slug stays, :path* and a trailing (.*) or :path(.*) become the catch-all *path(source: '/(.*)', the usual site-wide headers rule, becomes path = "/*rest").

# redirects() { return [{ source: '/blog/:path*', destination: '/news/:path*', permanent: true }] }
[[redirects]]
from = "/blog/*path"
to = "/news/*path"
status = 308          # permanent: true → 308, false → 307 (statusCode is kept)

[[headers]]
path = "/*path"
headers = { "X-Frame-Options" = "DENY" }

• images.remotePatterns/domains → [[images.remote_patterns]], deviceSizes/imageSizes → [images] allowed_widths
• i18n → [i18n] (localeDetection: false → path detection only)
• output: 'export' → the build script runs gio export; env → a .env hint
• A rule GioJS would match differently is skipped with a TODO instead of approximated: has/missing conditions, regex or optional parameters, external destinations, query strings in destinations, a root catch-all rewrite (/(.*), /:path*) outside beforeFiles - Next ran it only after checking pages and public files, GioJS would rewrite every request - and image pathname globs with a single * (one segment in Next.js; a gio.toml pattern's * matches at any depth, which would widen what the image proxy fetches). The one exception is a catch-all Next requires to be non-empty (/blog/:path+, /blog/(.*)): it becomes /blog/*path, which also matches /blog itself, with a TODO comment saying so
• experimental.serverActions points at page actions (bodySizeLimit → [server] max_body_bytes, allowedOrigins → [security.csrf] trusted_origins), experimental.ppr at export const shell = 'cache'; typed routes need no flag
• basePath, trailingSlash, webpack, other experimental flags and the rest are listed in the report - GioJS compiles with esbuild, so webpack and SWC options don't apply

An existing gio.toml is never overwritten. New tables are merged into it when no table or key would be defined twice; otherwise the converted sections go to gio.migrated.toml (not loaded by GioJS) for you to merge by hand. To convert just the config: npx create-giojs migrate --config next.config.js.

Server Actions → page actions

A form's Server Action becomes the page's action export: a POST to the page runs it, and <GioForm> (which the migration already put in place of the <form>) posts to it - with or without JavaScript:

// Next.js
async function createPost(formData: FormData) {
  'use server';
  await db.posts.create({ title: String(formData.get('title')) });
  redirect('/posts');
}
// <form action={createPost}>...</form>

// GioJS - app/posts/new/page.tsx
import { redirect, type ActionArgs, type WithActionData } from '@gio.js/core';
import { GioForm } from '@gio.js/react';

export async function action(req: ActionArgs) {
  const title = String((await req.formData()).get('title') ?? '');
  if (title === '') return { status: 422, data: { error: 'Title is required' } };
  await db.posts.create({ title });
  return redirect('/posts');
}

export default function NewPost({ actionData }: WithActionData<typeof action>) {
  return (
    <GioForm>
      <input name="title" />
      {actionData?.error && <p role="alert">{actionData.error}</p>}
      <button>Create</button>
    </GioForm>
  );
}

useFormStatus() becomes useGioFormState(), values passed with .bind() become hidden inputs, and useActionState's result is the page's actionData prop. The migration flags each of these.

What needs a human

• async Server Components - every GioJS page hydrates, so data loading moves into getServerSideProps (flagged on async pages and layouts)
• Providers in the root layout - the root app/layout is server-only HTML and never hydrates: context providers and interactive components go in a nested layout or the pages (flagged)
• Server Actions - the forms already post through <GioForm>; move each action's body into the page's export async function action(req) (fields from await req.formData(), answer with redirect(url) or { status: 422, data } to re-render with actionData - see Forms and Mutations). Actions called from code become route.ts handlers called with fetch()
• Middleware - declarative redirects, rewrites, headers, and session or cookie guards move to middleware.ts (defineMiddleware from @gio.js/core) or gio.toml, and run in the Rust layer before routing. Imperative request interception belongs in a Node plugin (GioNodePlugin with an onRequest hook)
• Unsupported app router files - template, parallel (@slot) and intercepting routes, generated (.tsx) icon/opengraph-image/twitter-image files (GioJS has no image generation: put a rendered image in public/) and nested sitemap.ts files (only app/sitemap.ts is served) are listed in the report
• Data caching - unstable_cache, 'use cache' and fetch() cache options become page caching: export const revalidate plus export const tags for the pages revalidateTag() should purge