Migrating from Next.js

Most Next.js projects will migrate to Swift Rust with minimal effort. The file-based router, the layout system, the data-fetching patterns, and the components are all familiar.

What stays the same

• The app/ directory layout
• layout.tsx, page.tsx, loading.tsx, error.tsx, not-found.tsx
• Dynamic segments ([slug], [...catchAll])
• Route handlers (app/api/foo/route.ts with GET, POST)
• The Image, Font, and Head components
• Server components by default, "use client" for client components

What changes

Package names

Replace next with swift-rust everywhere. Import paths become:

• next/image → swift-rust (the Image component)
• next/font/google → swift-rust/font/google
• next/font/local → swift-rust/font/local
• next/link → swift-rust (the Link component)
• next/navigation → swift-rust/router
• next/server → swift-rust/router

Removed

• next.config.js → swift-rust.config.json (JSON, not JS)
• next-env.d.ts → not needed; types come from swift-rust directly
• next/script → use a <script> tag with dangerouslySetInnerHTML or import the script at the top of a "use client" component
• useRouter from next/navigation → from swift-rust/router

Server actions

Server actions work the same way. The only difference is the import path.

Image loader

The loader prop on <Image> uses /_swift-rust/image instead of /_next/image. If you have a custom loader, point it at the new path.

Render modes

Set "rendering": "ssr-wasm" in swift-rust.config.json to match the Next.js App Router's behavior. Other modes ("ssr", "ssr-htmx", "wasm") don't have direct Next.js equivalents.

Step-by-step migration

1. Scaffold a new Swift Rust project alongside your existing one.
2. Copy app/, components/, and lib/ across.
3. Run a search-and-replace for from "next/ to from "swift-rust/ (or for just from "swift-rust).
4. Update package.json dependencies.
5. Update tsconfig.json paths if needed (Swift Rust uses the same "@/*" convention by default).
6. Run bun install and bun run dev.