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/script → swift-rust (the Script component)
  • next/form → swift-rust (the Form component)
  • next/cache → swift-rust (revalidatePath, revalidateTag, cache)
  • next/navigation → swift-rust/router
  • next/server → swift-rust/router

Upgraded & Replaced Primitives

  • dangerouslySetInnerHTML → <SafeHtml> & createTrustedHtml() from swift-rust. Unauthenticated raw strings injected in the browser are automatically blocked and escaped.
  • middleware.ts → proxy.ts (matches Next.js 16+ proxy convention; runs at the root and per-segment).
  • next.config.js → swift-rust.config.json or defineConfig().
  • next-env.d.ts → not needed; types come from swift-rust directly.

Server actions, PPR & Special Files

Server actions ("use server"), Partial Prerendering (experimental_ppr = true), "use cache", template.tsx, default.tsx, instrumentation.ts, robots.ts, and sitemap.ts all work out of the box with zero configuration changes.

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.