DEV Community: Yury Hryshchanka

Prerendering a page per device, and the cache key that has to agree

Yury Hryshchanka — Thu, 29 Oct 2026 05:56:17 +0000

A marketing page with no per visitor content should be built once and handed
out as a file, which is what prerendering means here: the build writes the
HTML, and the server answers with it instead of rendering again. The page I had
to do this to was not quite static. Its footer is an accordion on a phone and a grid
on a laptop, and a few sections below it differ the same way. Two rendered
versions of one document have to exist at the same time.

The browser can make that choice by itself, which is the first thing to rule
out. A CSS media query renders both versions and hides one, so the same text
sits in the document twice and every visitor downloads the one they will never
see. JavaScript picks after the page has loaded, so the first paint is a guess
and the reader watches it change. Either way the page ships markup the device
in front of it will not use. Choosing at build time means one version per file,
and the HTML a crawler reads is the HTML a phone gets.

Everything below happens inside the application, in the Next.js App Router, on
version 15. The same split can live a layer above it instead.

Inside the application, that means two files and one URL. A shared cache in
front of it keys on that URL and nothing else, so on its own it cannot tell the
two files apart. What it can do instead is split its own storage by device, and
making my split agree with its split decided the shape of everything else.

The whole thing, before the explanation

Two prerendered files per page, one public URL, and a rewrite that picks
between them before the request reaches a route. Everything below this section
is the reasoning. This is the code, and it runs.

A page opts in with one export, and refuses to render at its own path, where no
device arrives:

app/terms-of-use/page.tsx

import Layout from '@/app/_layout/Layout'
import type { DeviceSegment } from '@/lib/device'
import { notFound } from 'next/navigation'

export const isDeviceBasedSSG = true

export const metadata = { title: 'Terms of use' }

export default function TermsPage({ device }: { device?: DeviceSegment }) {
  if (!device) notFound()

  return <Layout device={device}>Terms of use</Layout>
}

A script turns that marker into one route per device, plus the list of paths
that got one:

scripts/generate-device-routes.mjs

import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { dirname, join, relative } from 'node:path'

const DEVICES = ['desktop', 'mobile']
const SOURCE_DIR = 'app'
const OUT_DIR = join('app', '(generated)')
const PATHS_FILE = 'lib/cacheable-paths.generated.ts'
const MARKER = /export\s+const\s+isDeviceBasedSSG\s*=\s*true/

// A folder named `(group)` adds no segment to the URL. A folder named `_private` is out of
// routing altogether, so a page under one is not a route and must not get a wrapper.
const isGroup = (name) => name.startsWith('(')
const isPrivate = (name) => name.startsWith('_')

function findMarkedPages(dir, routePath = '') {
  const entries = readdirSync(dir, { withFileTypes: true })

  const here =
    entries.some((entry) => entry.isFile() && entry.name === 'page.tsx') &&
    MARKER.test(readFileSync(join(dir, 'page.tsx'), 'utf8'))
      ? [{ routePath: routePath || '/', dir }]
      : []

  return [
    ...here,
    ...entries
      .filter(
        (entry) =>
          entry.isDirectory() && !isPrivate(entry.name) && join(dir, entry.name) !== OUT_DIR,
      )
      .flatMap((entry) =>
        findMarkedPages(
          join(dir, entry.name),
          isGroup(entry.name) ? routePath : `${routePath}/${entry.name}`,
        ),
      ),
  ]
}

// The import path goes into a string literal and never into a comment: a directory
// name may carry a line terminator, which ends a // comment and drops the rest into
// code the build compiles.
const wrapper = (importPath, device, metadataExport) => `// Generated. Do not edit.
import Page${metadataExport ? `, { ${metadataExport} }` : ''} from ${JSON.stringify(importPath)}

export const dynamic = 'error'
${metadataExport ? `\nexport { ${metadataExport} }\n` : ''}
export default function GeneratedDeviceRoute() {
  return <Page device="${device}" />
}
`

const marked = findMarkedPages(SOURCE_DIR)

for (const { routePath, dir } of marked) {
  // A wrapper is a route at a fixed path, so it cannot carry a parameter, and it sits
  // directly under the app root, so it cannot inherit a layout from the source's folder.
  if (routePath.includes('[')) {
    throw new Error(`${dir}: a device route cannot hold a dynamic segment (${routePath})`)
  }

  const ancestors = routePath.split('/').filter(Boolean).slice(0, -1)

  for (let i = 0; i < ancestors.length; i += 1) {
    const layout = join(SOURCE_DIR, ...ancestors.slice(0, i + 1), 'layout.tsx')

    try {
      readFileSync(layout)
      throw new Error(`${dir}: ${layout} would not apply to the generated route`)
    } catch (error) {
      if (error.code !== 'ENOENT') throw error
    }
  }
}

rmSync(OUT_DIR, { recursive: true, force: true })

for (const { routePath, dir } of marked) {
  const source = readFileSync(join(dir, 'page.tsx'), 'utf8')
  const metadataExport = /export\s+(async\s+)?function\s+generateMetadata/.test(source)
    ? 'generateMetadata'
    : /export\s+const\s+metadata\b/.test(source)
      ? 'metadata'
      : ''

  for (const device of DEVICES) {
    const outFile = join(OUT_DIR, device, routePath, 'page.tsx')
    const importPath = relative(dirname(outFile), join(dir, 'page')).split('\\').join('/')

    mkdirSync(dirname(outFile), { recursive: true })
    writeFileSync(outFile, wrapper(importPath, device, metadataExport))
  }
}

writeFileSync(
  PATHS_FILE,
  `// Generated. Do not edit.\nconst CACHEABLE_PATHS = ${JSON.stringify(
    marked.map((page) => page.routePath),
  )} as const\n\nexport default CACHEABLE_PATHS\n`,
)

console.log(`generated ${marked.length * DEVICES.length} routes for ${marked.length} pages`)

Run it before anything that reads the routes, and keep what it writes out of
the repository:

package.json

{
  "scripts": {
    "generate:routes": "node scripts/generate-device-routes.mjs",
    "predev": "npm run generate:routes",
    "prebuild": "npm run generate:routes",
    "pretypecheck": "npm run generate:routes",
    "pretest": "npm run generate:routes"
  }
}

.gitignore

# Written by scripts/generate-device-routes.mjs.
app/(generated)/
lib/cacheable-paths.generated.ts

Middleware rewrites the public path into the generated route, so the visitor's
URL and the canonical tag never carry a device:

middleware.ts

import CACHEABLE_PATHS from '@/lib/cacheable-paths.generated'
import { deviceFromHeaders, isInternalDevicePath } from '@/lib/device'
import { NextResponse, type NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl

  // Nothing links to the internal form, so a request carrying one was typed or crawled.
  if (isInternalDevicePath(pathname)) {
    return NextResponse.rewrite(new URL('/_not-found', request.url), { status: 404 })
  }

  if (!(CACHEABLE_PATHS as readonly string[]).includes(pathname)) return NextResponse.next()

  return NextResponse.rewrite(
    new URL(`/${deviceFromHeaders(request.headers)}${pathname}`, request.url),
  )
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

One device read that every page shares, and the guard the middleware just used:

lib/device.ts

import { userAgent } from 'next/server'

export const DEVICE_SEGMENTS = ['desktop', 'mobile'] as const

export type DeviceSegment = (typeof DEVICE_SEGMENTS)[number]

const LAYOUT_BY_CDN_TYPE: Record<string, DeviceSegment> = {
  mobile: 'mobile',
  tablet: 'mobile',
  desktop: 'desktop',
}

export function deviceFromHeaders(headers: Headers): DeviceSegment {
  const cdnType = headers.get('cf-device-type') ?? ''

  // Own keys only: outside a cache rule this header is whatever the client sent, and
  // `constructor` or `__proto__` would otherwise resolve to a member of the prototype.
  if (Object.hasOwn(LAYOUT_BY_CDN_TYPE, cdnType)) return LAYOUT_BY_CDN_TYPE[cdnType]

  return userAgent({ headers }).device.type === 'mobile' ? 'mobile' : 'desktop'
}

export function isInternalDevicePath(pathname: string): boolean {
  const [, first] = pathname.split('/')

  return (DEVICE_SEGMENTS as readonly string[]).includes(first)
}

And the response headers, because a prerendered route otherwise advertises a
year of shared caching to whatever sits in front of it:

next.config.mjs

import CACHEABLE_PATHS from './lib/cacheable-paths.generated.ts'

/** @type {import('next').NextConfig} */
export default {
  async headers() {
    return CACHEABLE_PATHS.flatMap((path) => [
      {
        source: path,
        has: [{ type: 'header', key: 'rsc' }],
        headers: [{ key: 'Cache-Control', value: 'private, no-store' }],
      },
      {
        source: path,
        missing: [
          { type: 'header', key: 'rsc' },
          { type: 'query', key: '_rsc' },
        ],
        headers: [{ key: 'Cache-Control', value: 'public, max-age=0, s-maxage=3600' }],
      },
    ])
  },
}

That is the implementation, on Next 15 with the App Router. Next 16 renames the
file to proxy.ts and the function to proxy, which I have not run. The rest
of this article is why each of those decisions is the one that survived, and
the two failures none of the code shows on its face: a build that stays green
while nothing is prerendered, and a cache that hands one visitor's layout to
everybody else.

The cache key is the path, and nothing from the request

Next keeps the HTML it prerendered in what it calls the full route cache. The
key for that cache is the resolved route path. In 15.5 it is one line of
next/dist/server/base-server.js:

let resolvedUrlPathname = getRequestMeta(req, 'rewroteURL') || urlPathname

and getFilePath in the file system cache turns that same string into a path
on disk. Nothing else from the request reaches it. Next does send a Vary
header for whatever caches the response downstream, but its own route cache
does not consult one.

The query string does not help either. I measured that rather than reasoning
about it: with the page not reading searchParams, ?device=m, ?device=d
and no query at all came back byte for byte identical, all three hashing to
4005cda574c9, one cache entry answering every one of them. A page that reads searchParams is not prerendered at
all, and whether that is a build failure or a silent fallback to rendering on
demand is the subject of a later section.

Rewrites declared in next.config do not create routes either, they point at
routes that already exist, so they add no dimension to the key. I pointed one
at a prerendered route from beforeFiles and another from afterFiles, and
both source URLs came back identical to the route itself, all three hashing to
d0fa5dfdb35c. One entry, three ways in.

Two variants therefore mean two paths, and the only varying input a
prerendered render can see is a route parameter.

Where the shape came from

I did not invent this. The shape comes from a comment by a Next collaborator in
a discussion about
serving a light and a dark theme out of one cache:

Prerender per known theme

generateStaticParams returns the theme list. Pages live under [theme]/. A
proxy rewrites /foo → /<cookie>/foo server-side, and redirects direct
visits to /light or /dark back to the unprefixed path so themed URLs
aren't shareable.

Each route ends up with one cache slot per theme.

HTML arrives themed. No FOUC, no JS required.

Server can branch on theme, that is, RTL, different components, distinct meta.

Read it with devices in place of themes and it says four things. Make the
variant a route parameter. Move the pages that want variants under that
parameter's folder. Let generateStaticParams prerender one copy per value.
Have middleware, the function that runs before a request reaches a route,
rewrite the public URL into the variant so the visitor never sees it.

He names two costs:

Switching theme is a server round trip, an actual navigation.

Proxy on every request, between you and your CDN.

Neither reaches this case. Nobody switches devices, so there is no switch to
pay for. And middleware was already running on every request here, for locale
routing and for putting visitors into experiments, so its cost was on the bill
before this feature existed.

Two parts of that I did not want.

A dynamic segment in the first position costs more than the URLs it agrees to
match. Once the first segment is a parameter, every first level path is a valid
route, and the framework's own not found stops firing for a wrong one, because
from its side nothing is wrong. Something inside the tree has to decide which values are real
and call notFound() for the rest, which makes that check the only place the
legal values are written down. A reader who wants to know what the site accepts
can no longer look at the folders, they have to open the code. A whitelist does
not rescue it either, because Next has no fall through: once a route matches,
notFound() renders the not found boundary rather than handing the request to
the next candidate route.

The shared parent folder fails more quietly. Every page that wants a variant
has to move under it, and pages that cannot have one stay where they are. Say
articles/ holds two pages, one that can be cached and one that reads a cookie
and therefore cannot. The first moves under [theme]/ and the second does not,
so articles/ now exists in two places at once. Add a page, and remember the
second tree. Rename a folder, and remember it again. The build is green either
way, and the mistake shows up as a page that quietly stopped being prerendered.

So the parameter went away, and two literal folders replaced it, desktop/ and
mobile/, each holding a real page file. A folder matches its own name and
nothing else, so an unknown value now matches no route at all. That is what
generateStaticParams and dynamicParams were there to arrange, and what the
guard was there to catch when they failed, so all of it goes.

What literal folders do not remove is the duplicated tree. They move it:
desktop/ and mobile/ each hold a copy of every marked page. What changes is
who keeps the copies in step. Two trees a person edits is the objection above.
Two trees a script writes is a build step, because nobody edits them and nobody
reviews them. That is the whole argument for generating them.

What the generator writes

The whole opt-in is one export, at the page's normal path:

app/terms-of-use/page.tsx

export const isDeviceBasedSSG = true

The script writes two things from it: a route per device, and the list of paths
that got one. The list is a module rather than a directory scan, because the
same code has to work wherever the rewrite runs, and because deriving it from
the marker is what stops it drifting away from the folders it names.

Each generated route carries no logic of its own:

app/(generated)/desktop/terms-of-use/page.tsx

// Generated. Do not edit.
import Page, { metadata } from '../../../terms-of-use/page'

export const dynamic = 'error'

export { metadata }

export default function GeneratedDeviceRoute() {
  return <Page device="desktop" />
}

The wrapper takes no props of its own on purpose. A page file is type checked
against the props Next passes a route, and a wrapper that declares anything
else fails that check. Metadata is re-exported, and a wrapper that forgets it
leaves the page with no title and no description, which is why the script reads
the source for a metadata export and emits the re-export only when it finds
one. The line that matters more than either of those is dynamic = 'error'.

The one line that turns a silent failure into a build failure

Nothing in a prerendered route's tree may read cookies(), headers() or
searchParams. That includes the layout and the not found boundary, which sit
in every route's tree. One such read anywhere puts the whole route back on per
request rendering, and the build stays green while it happens. The not found
page is the one that catches people out, and it is also the one page whose
device genuinely cannot be known, so it takes a fixed value rather than reading
for one.

dynamic = 'error' is what turns that class of mistake into a build failure,
and the failure names the API: Route /desktop/terms-of-use with dynamic = "error" couldn't be rendered statically because it used headers.

The variant you serve has to be the variant the cache stored

Everything above gets you two prerendered files and a rewrite that picks one.
Put a shared cache in front and a new failure appears, because the cache stores
one body per bucket of its own choosing, and it chose that bucket with its own
classifier.

Cloudflare, for one, can split a cache rule by device type and then sends the
origin a CF-Device-Type header carrying the bucket it used. If middleware
picks the branch with a User Agent parser while the edge keys on the CDN's
answer, then for every user agent where the two disagree, whoever arrives first
decides what the entire bucket serves to everyone behind them.

They disagree on real traffic, and not on anything exotic. A native app's
networking stack and a reading device asked to behave like a desktop both
landed in one bucket at the edge and another in my parser. The particular
agents will age, so take the category instead of the list: anything whose user
agent does not describe the screen it draws on.

Whatever you parse with has to collapse to the buckets the cache actually
holds. Mine had a third answer, unknown, for anything it did not recognise,
and under two buckets a third answer is not a third variant, it is a coin toss
about which of the two documents a visitor gets. The read above has no third
branch for that reason. Every disagreement I found became a test case.

The fix is one server side read, used by every page, taking the CDN's answer
first and the user agent second:

lib/device.ts

export function deviceFromHeaders(headers: Headers): DeviceSegment {
  const cdnType = headers.get('cf-device-type') ?? ''

  // Own keys only: outside a cache rule this header is whatever the client sent, and
  // `constructor` or `__proto__` would otherwise resolve to a member of the prototype.
  if (Object.hasOwn(LAYOUT_BY_CDN_TYPE, cdnType)) return LAYOUT_BY_CDN_TYPE[cdnType]

  return parseUserAgent(headers.get('user-agent') ?? '').isMobile ? 'mobile' : 'desktop'
}

Tablets map to the mobile layout, which means three buckets hold two documents
and the tablet copy duplicates the mobile one. That is the price of letting the
cache own the classification.

The internal paths have to be unreachable

Nothing links to /desktop/terms-of-use, so a request carrying one was typed or
crawled. It is also a real route, and I checked what happens without the guard:
it answers 200 and serves the document. The same page at a second URL, with
whatever search weight the real one has split between them.

lib/device.ts

export function isInternalDevicePath(pathname: string): boolean {
  const [, first] = pathname.split('/')

  return (DEVICE_SEGMENTS as readonly string[]).includes(first)
}

The rewrite goes to /_not-found with an explicit status: 404. Without the
status it is a soft 404: the not found page at 200, which is the duplicate the
guard exists to prevent, wearing a different hat.

What I would keep

Keep the variant as a path segment, because nothing else reaches the key. Keep
literal folders rather than an enumerated dynamic segment, because a folder
cannot match a value it is not named after. Keep one device classifier for the
whole application, and if a shared cache sits in front, make it the cache's
classifier. Keep dynamic = 'error' on every variant route. Keep a check that
reads the prerender manifest rather than the route table, and a second one that
requests the URLs nobody should request and expects a 404.

Keep a check on the bytes themselves, which asks a running build for the same
page twice and compares what comes back: same bytes inside one device class,
different bytes between classes, and no change when the request carries
cookies. Take the cookie names from the application's own constants rather than
retyping them, or the check sends a cookie nothing reads and quietly passes on
two requests that both carried nothing.

Keep the generator, and know what you are buying with it. Two hand written
wrappers of four lines each do the same job today, for two cacheable pages. The
day somebody marks a third page, the wrappers and the path list have to follow,
and a person who forgets gets no error, just a page quietly rendering per
request again. A marker that generates both of them cannot be forgotten.

That is the only thing the script buys. The price is a prebuild step in front
of every command a developer runs, stack traces that point at files which are
not in the repository, an error that names a wrapper when the mistake is in the
source page, a tree that can be stale, and a script that writes paths into code
the build then compiles. For two pages it is a bad trade. For a site where
anybody can mark a page, I would make it again.

The generated tree is in .gitignore, and that is the call in all of this I am
least settled about. It keeps the repository honest about what a person wrote.
It also means nothing in the repository shows a reader what actually gets built,
and a stack trace can point at a file they cannot open.

The code here is a rewrite of what shipped, generic enough to drop into any
project. To be sure the rewrite is more than a sketch I built a clean Next 15.5
app out of exactly these files and drove it, and the build output, the response
headers and the hashes above come from that app. What a local app cannot show
is how two classifiers disagree on real traffic, and that part comes from the
application the design shipped in.

Opening the app from a link, and what happens when it is not installed

Yury Hryshchanka — Wed, 14 Oct 2026 21:12:39 +0000

A link on the web should open the app on the exact screen that the link points
to. Sometimes the app is not installed. In that case the link should do
something better than showing the person a page that only says the app exists.

The second part is the hard one. The browser will not tell you whether an app
is installed, and it should not: a page that could list your installed apps
would be a fingerprinting tool.

Here is an example that runs in production. Open it on a phone and not on a
laptop:
Pavel Durov's channel in the Nicegram catalogue.
The Open button on that page is the subject of this article.

Nicegram is a Telegram client, so the fallback here goes to Telegram itself. If
the app is installed, the phone opens Nicegram. If the app is not installed, the
same tap opens Telegram on the web, and it carries the channel you came from.
There is one URL behind that button and there are two results. None of my code
chose between those two results.

The guess this replaced

Before the server was involved in any of this, the page tried to work it out
alone. I inherited a version that was built from
this Stack Overflow answer. It was
copied so closely that even the variable name was the same:

var now = new Date().valueOf();
setTimeout(function () {
    if (new Date().valueOf() - now > 100) return;
    window.location = "https://play.google.com/store/apps/";
}, 25);
window.location = "appname://";

That answer is from April 2018 and its score is minus one. That is where code
that ran in production for years actually came from. I prefer to write this down
rather than suggest that the code came from a specification.

The idea works like this. The page navigates to a custom URL scheme. A custom
URL scheme is an address like appname:// that an app registers for itself when
it is installed. Then the page starts a timer. If the app takes the navigation,
the browser suspends the page, which means the page stops running its code. So
when the timer finally runs, it runs late and does nothing. If the page is still
running and the timer fires on schedule, the code assumes there is no app and
goes to the store page instead.

The timer is twenty-five milliseconds and the threshold is one hundred
milliseconds. Both numbers are guesses about how fast a phone switches between
apps. Somebody measured them on one device, one time. No browser ever agreed to
respect either number. A busy phone can need more than one hundred milliseconds
even when the app is installed, and then the timer decides the app is not there.

Look at what the elapsed-time check really reads. The check does not ask whether
the app exists. The check asks whether the page stopped running, and it treats
that as the same question. The scheme fires, focus leaves for the app, the page
freezes, the timer runs late, and nothing happens. That is the happy path, and
it is built on a promise that no browser ever made.

So it does not always go that way. Some browsers keep the timer running while
the app is starting. Then the check passes, the page navigates to the store, and
the app opens as well. Both things happen. The person is now inside the app, and
whatever they do there, the browser is sitting on a page that the person never
chose, waiting for them to come back to it.

It gets worse when the person comes back. Imagine they return to the browser one
minute later. Far more than one hundred milliseconds have passed, so the same
code now reads that delay as proof that the app took the link. The story that
the page tells about what happened depends on how long somebody spent somewhere
else.

Then the platforms ended the argument. The Android answer with the highest score
starts with a line that its own author went back and added years later:
UPDATE: Google broke this. On the Apple
side, an answer from January 2017 says it
plainly. The behaviour changed in iOS 9.2 in order to push developers onto
universal links. None of this was ever a contract that you could look up. It was
only behaviour, and behaviour moved.

Give the decision away

Universal links on iOS and App Links on Android turn this around. A universal
link, and an App Link on Android, is an ordinary https:// link that an app can
claim as its own. At install time the app declares which URLs on your domain
belong to it. After that the operating system owns the decision. The operating
system is the one component in this story that actually knows what is installed,
because the operating system did the installing.

The setup is not what this article is about. There is a file that you host on
your domain, and there is a declaration that the app ships with. The platform's
own documentation covers both of them properly. The part that nobody writes down
is what happens next.

One path, not the whole site

The claim of the app does not have to cover your whole domain. Point the claim
at a single path, and keep the real destination in a query parameter:

const UNIVERSAL_LINK_ORIGIN = 'https://www.example.com'

export const linkToApp = (target: string) =>
  `${UNIVERSAL_LINK_ORIGIN}/deeplink?url=${encodeURIComponent(target)}`

If the claim covers every path, then your pricing page and your support articles
both become candidates for a handoff. A handoff means that the operating system
opens the app instead of the page. Then you will spend a year explaining why a
help page opened the app. A single path also gives you exactly one place on the
server to put the fallback, which is where this article is going.

The link has to leave the site to work

This is the rule that makes people think their setup is broken when the setup is
fine.

A universal link does not hand off when the person clicks it on a page that is
already on the same domain. The browser reads that click as ordinary navigation
inside the site that the browser is already showing, so the browser keeps the
navigation. Your link is correct, your association is correct, and nothing
happens.

So the link has to point at a host that is technically different. The page sits
on example.com and the link goes to www.example.com. For a reader these are
the same site. For the check inside the browser they are different hosts. This
is not a decision about canonical URLs, and it is not cosmetic.

www is a convention here and not a requirement. The rule is about hosts, and
any host you control will do as long as it is not the one serving the page.
The deep link vendor Branch documents it, quoted in an answer from 2016,
as a rule about crossing domains rather than about a particular name:
a link on one host pointing at another host opens the app, and a link pointing
at the same host does not. So the second host can be a dedicated subdomain that
exists for nothing else, and what it serves when the app does not take the link
is the subject of the rest of this article.

The same source gives two more limits, and both of them are worth knowing before
you spend a day looking for a bug you do not have. A link pasted into the
address bar never opens the app. And a navigation started from JavaScript does
not open the app either, unless it happens as part of a real user action. If you
build the URL in code, the URL still has to be followed by a person clicking
something.

A request that arrives is the answer

I got here by turning the old code around. That code put the watching on the
web side: fire the scheme, watch the clock, guess from whether the page was
still alive. I wanted the opposite. Nothing of mine should watch anything, and
the request should reach my server only when there is no app to take it. That
moves the decision to the only place that can actually make it, which is the
operating system.

The browser is the program that makes the request. The browser also knows about
the claim of the app, because the operating system recorded that claim. So the
browser tries the app first. If the app is not installed, or if the app declines
the handoff, the browser has nothing left to do except the thing that browsers
do, which is to ask the server.

This means that a request landing on my own server carries information. That
request is the answer to the question I could not ask directly, and the answer is
handed over by the only party that has it.

I had no proof of that ordering when I wrote the branch. It was an assumption
about how the chain is wired, and I built on the assumption anyway. The
assumption held.

The rest follows from there. When the claim fires, the request never leaves the
phone. The operating system hands the URL to the app, and your server never
hears about it. Silence is the success case. When the claim does not fire, the
request arrives, and a request arriving at /deeplink is the operating system
telling you that it had nothing to hand this URL to. You never detect anything.
You get told, and you get told by absence.

That turns the whole problem into an ordinary server branch. The code below is
Next.js 15, and in that framework the file has to be called middleware.ts and
has to sit at the root of the project. Nothing about the idea depends on the
framework: any server that can answer one path before the router does will do.

import { NextResponse, type NextRequest } from 'next/server'

const ALLOWED_ORIGINS = ['https://chat.example.net']

function resolveTarget(raw: string | null): string | null {
  if (!raw) return null

  try {
    const parsed = new URL(raw)

    return ALLOWED_ORIGINS.includes(parsed.origin) ? parsed.href : null
  } catch {
    return null
  }
}

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname !== '/deeplink') return NextResponse.next()

  const target = resolveTarget(request.nextUrl.searchParams.get('url'))

  return target
    ? NextResponse.redirect(new URL(target))
    : NextResponse.rewrite(new URL('/download', request.url))
}

Note which of the two branches is a redirect and which is a rewrite, because
they are not interchangeable here. A redirect tells the browser to go and
request a different URL, and the address bar changes to that URL. A rewrite
serves the content of another path from the same request, and the address bar
does not change. The Telegram link has to be a redirect, because the
destination is somebody else's site. The download page is a rewrite, so the
person stays on /deeplink and a reload does not bounce them anywhere.

The allowlist in that code is not tidiness. The ?url= parameter is written by
whoever shares the link, so redirecting to whatever it says publishes an open
redirect on your own domain: a URL of yours that sends people wherever an
attacker picks. Phishing campaigns are built out of exactly that, because the
recognisable part of the address is your domain. So compare the parsed origin
against a list of exact origins. A substring check on the hostname passes
https://chat.example.net.evil.test, and you will not notice until someone else
does.

Absence is strong evidence and it is not proof. Every condition from earlier in
this article is also a way for the request to arrive from a phone that does have
the app: the link pointing at the host the page is already on, the link pasted
into the address bar, the navigation started by code rather than by a person.
Your server sees the same request in all of those cases as it sees from somebody
who has never installed anything. So pick a fallback that stays tolerable when
you are wrong.

Where to send someone who does not have the app

For a long time the fallback was the download page, with the store buttons on
it. That is the obvious answer. The person has no app, so offer them the app.

I changed it in July 2025, and the reasoning has held up better than I expected.
Someone who taps a link to a conversation wants the conversation. A store page
asks that person to install something first, and then to find their way back to a
link they no longer have. Most people stop at the first step. The few people who
finish arrive at an app that has no idea what link sent them.

So the fallback sends them to the same conversation on the platform where that
conversation already lives. They get what the link promised, on the web,
immediately.

The store page kept a job. The branch goes to the store page when the link
carries no usable destination at all. A store page is a reasonable fallback when
there is nothing at the other end of the link. A store page is a bad fallback
when there is something there.

Notice what this does when the guess is wrong. Somebody who does have the app
gets sent to the same conversation on the web, which is where that person was
going anyway. So being wrong costs almost nothing. That is luck, but it is the
kind of luck you can arrange on purpose.

The chain, in order

A page on example.com wants to point at the conversation
https://chat.example.net/c/123, so it builds this:

https://www.example.com/deeplink?url=https%3A%2F%2Fchat.example.net%2Fc%2F123

Walked from one end to the other:

Your code builds that URL on www.example.com, a host the page is not currently on, which is the whole reason www is in there.
The tap goes to the operating system, which checks the URL against the claims it recorded when apps were installed.
If a claim matches, the app opens and reads the same ?url= parameter to work out which screen to show. Your server sees nothing.
If no claim matches, the request reaches /deeplink, your allowlist accepts https://chat.example.net, and the person is redirected to https://chat.example.net/c/123.

Only the first step and the last step are yours. The two middle steps belong to
the operating system and to the app. This design is worth copying because it
stops pretending otherwise.

The question that matters is not how to find out whether an app is installed.
You cannot find that out, the platforms have decided that you should not, and
every technique that claims otherwise is guessing. The question is what the
person gets when the app is not there. That is a product decision in a technical
costume, and it gets made by whoever writes the fallback branch, usually while
that person is only trying to get a link to work.