Skip to content

Add a Next.js-to-webjs migration guide doc page #273

Description

@vivek7405

Problem

webjs's positioning is explicitly Next-adjacent (app/ router, page/layout/error/loading/not-found/route/middleware, metadata API, server actions), so Next users are the primary adoption funnel, but there is no doc translating Next idioms (Server/Client Components, 'use client'/'use server', next/link, next/image, getServerSideProps, route handlers, middleware) into webjs equivalents. A Next dev hits the RSC mental model the AGENTS.md execution-model section warns against with no user-facing doc to correct it.

Design / approach

Add a /docs/migrating-from-nextjs page in the nav with a concept-mapping table, an explicit statement of the no-RSC execution model and the .server.ts boundary, and a before/after code sample. Docs only.

Web-standards fit: Documentation only; it maps Next idioms to webjs's standards-based primitives, adding no code.

Prior art: Next.js Migrating-from guides, Remix Next->Remix guide, SvelteKit Migrating-from-Sapper.

Acceptance criteria

  • A new /docs/migrating-from-nextjs page is added to the nav
  • A concept-mapping table maps RSC/'use client'/'use server' to isomorphic modules + .server.ts RPC, next/link to , getServerSideProps/generateStaticParams to async page fn, route handlers to route.js, middleware to middleware.js, next/image as not provided
  • It explicitly states the no-RSC execution model and the .server.ts boundary
  • At least one before/after code sample (a Next page and its webjs equivalent)
  • Cross-linked from getting-started and architecture pages
  • Tests cover the new behaviour at the applicable layer(s)
  • Docs / AGENTS.md / CONVENTIONS.md updated if the public surface changed

Filed from the production-readiness audit (webjs vs Next.js / Remix / Rails / Turbo / Lit). Theme: docs. Priority: P1. Kept to webjs identity: no-build, progressive enhancement, web-components-first, AI-first, batteries-included, close to web standards.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions