Skip to content

docs: add a Next.js to webjs migration guide - #304

Merged
vivek7405 merged 1 commit into
mainfrom
docs/migration-guide
Jun 3, 2026
Merged

docs: add a Next.js to webjs migration guide#304
vivek7405 merged 1 commit into
mainfrom
docs/migration-guide

Conversation

@vivek7405

Copy link
Copy Markdown
Collaborator

Closes #273

What

webjs 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 and layouts), and the .server file as the one server boundary (RPC plus source-protection, not RSC).
  • A concept-map table: Server/Client Components and use client/use server to isomorphic modules plus .server RPC, React hooks to signals, next/link to a plain <a>, 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.
  • 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.

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 .server query, the async page function with PageProps, the component using the declare plus constructor-default reactive-prop pattern, and the tag matching the register() call).

Tests

test/docs/migration-page.test.mjs: the page serves, states the no-RSC model and the .server boundary, 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.

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 vivek7405 self-assigned this Jun 3, 2026

@vivek7405 vivek7405 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@vivek7405
vivek7405 merged commit 01bdf9c into main Jun 3, 2026
5 checks passed
@vivek7405
vivek7405 deleted the docs/migration-guide branch June 3, 2026 10:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant