PRNext and Next.js: compatibility and migration guide

#Align the version and prerequisites

This release declares Node ^22.23.4 || ^24.22.1 || >=26.12.1. Its React, React DOM and react-server-dom-webpack peers are 19.3.1. Keep optional native dependencies enabled: the native component must match the framework version.

The commands below use npm. Keep pnpm or Yarn if the project already uses them and read the documentation shipped in the package. Work on a branch or isolated copy, preserving the original lockfile. Published native packages do not require consumers to install Rust.

node --version
npm install --save-exact @thomas.f/prnext@0.1.18-alpha react@19.3.1 react-dom@19.3.1 react-server-dom-webpack@19.3.1
npx --no-install prnext migrate --dry-run
npx --no-install prnext migrate --check --json

#Identify features that need focused checks

Routing conventions, Server Components, actions, navigation and styles are among the areas adapted by PRNext. Scope depends on configuration and the path executed. This matrix identifies application checks rather than assigning universal compatibility to each feature family.

#Read the plan before applying migration

The dry run lets you review proposed script and dependency changes. The audit should also identify configuration and source conflicts. Keep one next.config.* or prnext.config.* file; renaming it does not make an unknown Next.js option supported.

When the plan is appropriate, apply migration, check configuration and build. typecheck requires TypeScript and a tsconfig in the application. Migration retains sources and Next.js; public next/* imports can remain. Avoid blanket import replacements or hiding peer conflicts with --force.

npx --no-install prnext migrate
npx --no-install prnext check --json
npx --no-install prnext typecheck
npx --no-install prnext build

#Compare responses from separate servers

Start the Next.js reference on an available port and the candidate on another. paths.json contains a JSON array of concrete routes, such as ["/", "/products/demo", "/api/health"], replaced with your application’s paths. Keep cookies and secrets out of it.

The comparator checks samples of public GET responses. It does not authenticate requests or follow redirects. Its timings are not a controlled benchmark. A favorable result still requires browser checks for styling, hydration, mutations and authenticated states.

npx --no-install prnext migrate --check --against http://127.0.0.1:3000 --candidate http://127.0.0.1:3001 --routes paths.json

#Verify the journeys that make the product work

Exercise login, logout and a business action. Check back navigation, errors, loading states and cookies. For a form, verify both the stored result and the displayed state after the response. HTTP status does not describe the whole interaction.

Add isolation checks with two sessions: private responses and cached data must not cross between them. If you use private Next.js imports, custom loaders or advanced routing, keep a minimal example of the tested path. Those dependencies can change the evaluation.

#Decide after functional verification

Keep the exact version, lockfile, tested cases and any incompatibilities. If a feature is missing, identify the API and scenario involved. A precise limitation is more useful than an overall compatibility percentage.

Then measure expensive routes under matching resource constraints. Retain the reference until the candidate meets your criteria. Database migrations need their own rollback plan; restoring package.json does not undo them.

Choose PRNext for your application’s requirements

Measure SSR after functional verification