Allow Different Implementation for Function at Build Time depending on whether Function will be Run on the Client or the Server

[rweisman-cube]

Goals

1. Allow using a different implementation for a function if running on the client vs. the server (be it server-side rendering, serverless function, etc.)
2. Allow the build to complete so long as the client-side implementation doesn't rely on any server-side-only code even if the server-side implementation does

Non-Goals

1. Selecting a different implementation at runtime, which is already described in many places, e.g. Server-side only method to ensure server-only code is never sent to the browser #5354

Background

What I'm Trying to Accomplish

• Ultimately, I want to pass geolocation information to a backend
  • In cases where the client calls, I can check where the request is coming from on the backend
  • In cases where the server side calls, I need Vercel to append geo info as the backend can only see that the request originates from Vercel's servers
• The recommended way to do this is to call geolocation on the headers, but that requires importing next/headers, which is only available from the server-side, e.g. something like:

import { headers } from 'next/headers';
import { geolocation } from '@vercel/edge';

async function serverSideFetch(url, init) {
  const reqHeaders = headers();
  const { city, country, countryRegion, region, latitude, longitude } = geolocation({headers: reqHeaders});
  // ... append those values as headers to the "init" ...
  return fetch(url, modifiedInit);
}

Desired Behavior

In order for this to work consistently:

• Every server-side fetch in the application must append these headers on every call out to the backend
• Client-side calls do not need to append these headers

The Blocker

• Replacing all calls to fetch with this function doesn't work because any client code calling it will fail to build due to the first import
• The usual typeof window === 'undefined' trick doesn't work as the application never passes the build phase
• Since code can be shared between client and server, e.g.
  • React components that can be server-side or client-side rendered
  • helper functions that can be called from anywhere, be it client or server
    ...accomplishing the above requires a different implementation for the client vs the server.

There are a lot of assumptions here and my understanding of Vercel's environment is still evolving - there's probably an easier way to accomplish what I want to accomplish, but I can't find one. Does anybody have any thoughts?

Proposal

One of:

• a way to indicate that a particular file has a "split" implementation
  • i.e. an explicit way to mark a pair of functions as the "client" and "server" implementations in that file
• a way to specify conditional compilation by environment in package.json
  • i.e. two implementations in separate files, server-side takes one, client-side takes the other
• allow dynamic imports of server-only code within a conditional typeof window === 'undefined' as works for runtime
• Server-side only method to ensure server-only code is never sent to the browser #5354 suggests that this can be done when deployed with express, possibly a similar approach could be taken
• Possibly related? Conditional asset inclusion based on build configuration #63495

Alternate approaches:

• allow importing server-side only code such as next/headers from the client-side with the understanding that it returns no data