· By John Kavanagh

Retiring getInitialProps Without Changing Page Behaviour

Photograph of socket wrenches and extension bars in a red toolbox.
Image by Paul Rosenthal, licensed from Unsplash.

Deleting getInitialProps is straightforward. Working out why it was there takes a little longer.

A custom App might load navigation, pass through a page's data, read an account cookie, and initialise a provider. Moving the account lookup into getStaticProps can turn a private response into a public page.

With the data methods introduced in Next.js 9.3, I can choose the lifetime of each page's data more explicitly. I still need to preserve what the page promises its users. The function name is the easy part of that decision.

My example is a small repair café catalogue with a public listing, an account page, and a shared counter. The counter is deliberately unremarkable. If changing a data loader resets it, I've changed more than a data loader.


Write down What Each Route Promises

Before touching the implementation, I give each route a short contract.

The catalogue is public and may use the content approved for the current release. The account view belongs to the requesting user and must reflect their cookie and selected tab. The About page needs no request data. Existing missing‑page responses, errors, and redirects must keep their status and destination.

Those rules decide the replacement. They also expose an awkward question: does the catalogue really permit release‑time freshness? If it promises a fresh count on every request, moving it to static generation would be a regression. I would use getServerSideProps instead.

I covered that choice in my article on static generation and server‑side rendering. Here, I'm making the decision for each existing route and recording the consequences before changing its implementation.

My comparison includes both the first document request and navigation through a Link. A page that works after a refresh can still fail when reached from another page. getInitialProps can run in the browser during those transitions, where req and res are not waiting for it.


Separate the Wrapper from the Work

This custom App contains a common forwarding method:

function FixtureApp({ Component, pageProps }) {
  return (
    <Shell>
      <Component {...pageProps} />
    </Shell>
  );
}

FixtureApp.getInitialProps = async ({ Component, ctx }) => ({
  pageProps: Component.getInitialProps
    ? await Component.getInitialProps(ctx)
    : {},
});

It delegates to the page; it does not perform useful shared data loading itself. Once the pages no longer need that forwarding path, the method can go. The Shell stays where it is.

A real App may have more responsibilities. I separate them first. Public navigation data, an account lookup, and a provider's component identity do not acquire the same lifetime merely because somebody put them in the same file.

My custom App and Document article explains those wrappers. Moving a loader does not require moving the provider, wrapping it in a newly defined component, or adding a pathname key. Any of those changes can remount state which was previously preserved.


Move the Public Catalogue Deliberately

In the legacy example, the catalogue's getInitialProps reads a public API endpoint. The endpoint projects the source record into a title and count. An internal staff note never belongs in the page props.

The migrated page reads the same public projection during generation:

export async function getStaticProps() {
  const record = await readCatalogue();

  return {
    props: {
      title: record.title,
      count: record.count,
    },
  };
}

The component receives the same shape. The data now has a different lifetime, which is acceptable only because the route contract permits it.

I check that distinction by building with a count of three, changing the source to four, and requesting the page again. The legacy route reads four. The generated route still reads three. That is expected release‑time behaviour, not a cache bug to conceal in the test.

Generation also makes source availability a build concern. When the fixture's public content is unavailable, the build fails. Returning an empty list would make it green, but would also publish a different page. I would rather keep the previous working release available whilst fixing the content dependency.

The projection remains necessary even though the loader runs on the server. Props are serialised for the browser. Removing a client‑side API call does not make everything returned by its replacement confidential.


Keep Account Work on the Request

The account page uses getServerSideProps. Its loader reads the current request's cookie, validates the supported query value, and returns only the small view the component needs. It also marks the response private and unsuitable for storage.

The fixture uses two fixed identities, Alice and Bob, to make accidental reuse obvious. That is a test input, not an authentication system. A real account still needs its normal session validation and authorisation.

I request both identities directly, then navigate to the account page in the browser. The displayed name must match the current fixture cookie, and ?tab=details must survive both routes into the page.

An upstream exception must remain an exception. Catching it and returning an empty successful account object changes the failure contract. My deliberately thrown account error produces a 500; an unknown route remains a 404. The existing redirect is tested separately and retains its 302 and destination. I leave that route's loader alone during this migration rather than bundling another behaviour change into it.


Prove That the App Method Has Gone

There is a useful negative control here. I build the migrated pages again whilst deliberately leaving App.getInitialProps in place.

The explicit getStaticProps catalogue is still generated. The plain About page, however, remains dynamic. Removing the leftover App method restores that page's automatic static optimisation. Treating the App opt‑out as a ban on every form of generation would explain this result incorrectly.

In the browser, I increment the shared counter twice before following the catalogue and account links. It must still show two afterwards. The test also records the data requests: the legacy page calls its public API, whilst the migrated page retrieves the appropriate Next data response.

I disable link prefetching and activate the links with the keyboard for that comparison. Request counts need controlled conditions; they are not a universal performance claim. I also inspect the generated HTML and JSON for the private staff‑note marker, rather than assuming an invisible field stayed on the server.

The migration is ready when those checks describe the behaviour I intended to keep, including the freshness policy I explicitly accepted. I keep the previous implementation available for rollback and migrate the next route separately. There is no prize for removing every old method in one sitting.

Postscript

November 2026: I've added the migration comparison to my Pages Router regression lab, alongside my production‑request tests. It runs the same three scenarios against Next.js 9.4.4 with React 16.13.1 and the current companion's pinned Next.js 16.4.6 with React 19.3.1. The older framework was checked using Node 16.13.1 and Chrome 157, so this reconstructs its behaviour without claiming a period browser or Node environment. The current run also records an extra background HEAD request for generated‑page data. That is another reason to keep request‑count assertions tied to the version being tested.

Downloadable Resource

  • Next.js Pages Router Regression Lab

    Test production routes, data‑loader migration, and layout state. Compare real navigation, user/workspace resets, history, focus, errors, and private data.

    Download ZIP

Need a senior engineer involved?

I can work directly in the codebase, review the architecture, or support the team through delivery when the work needs more than extra hands.