docs: add a Next.js to webjs migration guide - #304
Conversation
webjs's positioning is explicitly Next-adjacent (the app/ router, the page/layout/error/loading/not-found/route/middleware conventions, the metadata API, server actions), so Next users are the primary adoption funnel, but there was no doc translating Next idioms into webjs equivalents. A Next dev arrives with the RSC mental model the execution model deliberately does not have, and nothing user-facing corrected it. Add /docs/migrating-from-nextjs: the mental-model shift stated explicitly (no server/client component split, isomorphic modules that hydrate (components) or do not (pages/layouts), the .server file as the one server boundary), a concept-map table (Server/Client Components and use client/use server to isomorphic modules plus .server RPC, hooks to signals, next/link to a plain anchor, next/image as not provided, getServerSideProps to an async page function, generateStaticParams to per-request render plus revalidate, route handlers, middleware, next.config to the webjs.* block), and a before/after sample (a Next Server+Client Component pair and its webjs page-plus-component equivalent). Added to the Getting Started nav and cross-linked from getting-started and architecture. Closes #273
vivek7405
left a comment
There was a problem hiding this comment.
A migration guide is only useful if every mapping is real, so I verified the webjs side of each concept-map row against the framework rather than trusting it. They all check out: signals and computed are exported from core, the page-function signature matches PageProps, export const revalidate is the real HTML-cache opt-in, the Metadata type and metadata.jsonLd exist, basePath and WebjsConfig exist, and cache() takes the {key,ttl,tags} shape with revalidateTag/revalidatePath as the invalidators. The before/after sample is the highest-stakes part since it is copy-pasteable, and it is correct: the .server query path is right, the component uses the declare-plus-constructor-default reactive-prop pattern (not a class-field initializer that would break reactivity), and the register tag matches the element used in the page. All cross-links resolve. Clean. Good to merge once CI is green.
Closes #273
What
webjs is explicitly Next-adjacent (the
app/router, thepage/layout/error/loading/not-found/route/middlewareconventions, the metadata API, server actions), so Next users are the primary adoption funnel, but there was no doc translating Next idioms into webjs equivalents. A Next dev arrives with the RSC mental model the execution model deliberately does not have, and nothing user-facing corrected it.Add
/docs/migrating-from-nextjs:.serverfile as the one server boundary (RPC plus source-protection, not RSC).use client/use serverto isomorphic modules plus.serverRPC, React hooks to signals,next/linkto a plain<a>,next/imageas not provided,getServerSidePropsto an async page function,generateStaticParamsto per-request render plusrevalidate, route handlers, middleware,next.configto thewebjs.*block.Added to the Getting Started nav and cross-linked from getting-started and architecture.
Accuracy
A migration guide that maps to a wrong equivalent misleads, so the review verified every webjs-side claim against the framework and confirmed the before/after code sample is correct, idiomatic, copy-pasteable webjs (the
.serverquery, the async page function withPageProps, the component using thedeclareplus constructor-default reactive-prop pattern, and the tag matching theregister()call).Tests
test/docs/migration-page.test.mjs: the page serves, states the no-RSC model and the.serverboundary, the concept map covers each required Next idiom, the before/after sample is present, and the nav entry plus the getting-started and architecture back-links resolve.Scope
Touches only
docs/+test/docs/. No framework code. No version bump.