Migrate site from Gatsby to Next.js (App Router)

[jimmyandrade]

Context

The Multei! site (@multei/web) runs on Gatsby 2 (React 17, legacy plugins). That stack is outdated and friction-heavy locally (modern Node, sharp/ARM, OpenSSL/Webpack, abandoned plugins such as gatsby-plugin-prefetch-google-fonts).

Goal

Migrate the site to the latest stable Next.js (16.x line, App Router), preserving current behavior and content, with modern DX and deploy.

Motivation

• Gatsby 2 and related dependencies do not track current Node LTS or Apple Silicon without workarounds.
• The Gatsby ecosystem is relatively stagnant; Next.js is the market default for React sites on Vercel.
• App Router, Server Components, Turbopack, and current tooling improve performance, DX, and maintainability.
• Easier alignment with Vercel auth, APIs, env vars, and CI.

Suggested scope

Discovery

• Inventory routes (src/pages), layouts, components, and critical dependencies (Material UI v4, Recoil, muy/metax, maps, images).
• Map Gatsby plugins to equivalents (SEO/helmet, sitemap, manifest/PWA, sharp/images, fonts, Material UI).
• Define target: Next.js 16 (App Router) + React 19, TypeScript (in this migration or as a follow-up).

Migration

• Scaffold Next.js and app/ structure (layouts, pages, Metadata API).
• Port pages and components; replace gatsby-image / asset GraphQL with next/image (or equivalent).
• Replace react-helmet / metax with Next Metadata / Open Graph.
• Review global state (Recoil) and hooks; align with Server/Client Component patterns.
• Upgrade or replace Material UI v4 (evaluate MUI v6/v7 or the current design system).
• Fonts: replace the prefetch plugin with next/font.
• Configure sitemap, robots, and PWA/manifest as needed.
• Tests: migrate Jest/Cypress to the new entrypoint; smoke E2E on main routes.

Delivery

• dev/build/start scripts, env vars, and deploy (Vercel/Netlify) equivalent to today’s flow.
• Remove Gatsby and orphaned dependencies; document how to run the project.
• Cutover plan (preview → production) and rollback.

Out of scope (for now)

• Broad visual redesign (except what the stack change requires).
• Large business-domain refactors unrelated to the migration.

Acceptance criteria

• Site runs on current Node LTS without legacy workarounds (openssl-legacy-provider, sharp hacks, etc.).
• Main routes and flows match the current Gatsby site.
• Production build and preview deployables work.
• Critical tests (unit/E2E) are green on the new stack.
• README updated with development instructions.

Notes

• When starting implementation, pin the latest stable Next.js available at that time (today: 16.2.x; evaluate 16.3 once out of preview).
• Prefer small incremental PRs (scaffold → pages → assets/SEO → cleanup).
• Related: hosting move in Migrate hosting from Netlify to Vercel #416.

[jimmyandrade]

Linked from npm deprecation inventory #445 / remediation #448 — Gatsby 2 transitive deprecations (webpack4, eslint-loader, @hapi/joi, core-js@2, etc.) clear naturally with the Next.js migration.