Skip to main content

@idhub/identity-adapter-nextjs/middleware

Interfaces​

AnonymousIdCookieConfig​

Defined in: identity-core/build/esm/index.d.ts:52

Properties​

domain?​

optional domain?: string

Defined in: identity-core/build/esm/index.d.ts:56

Cookie domain, e.g. '.example.com' for cross-subdomain sharing.

httpOnly?​

optional httpOnly?: boolean

Defined in: identity-core/build/esm/index.d.ts:60

Must stay readable by vendor client SDKs. Default: false.

maxAge?​

optional maxAge?: number

Defined in: identity-core/build/esm/index.d.ts:58

Seconds. Default: 31536000 (1 year).

name?​

optional name?: string

Defined in: identity-core/build/esm/index.d.ts:54

Cookie name. Default: '_anon_id'.

sameSite?​

optional sameSite?: "Strict" | "Lax" | "None"

Defined in: identity-core/build/esm/index.d.ts:62

Default: 'Lax'.

secure?​

optional secure?: boolean

Defined in: identity-core/build/esm/index.d.ts:64

Default: true in production, false in local dev over http.

IdentityMiddlewareConfig​

Defined in: identity-adapter-nextjs/src/middleware.ts:17

Everything in this module's import graph must stay Edge-runtime safe. @idhub/identity-core only touches Web Standard Headers and crypto.randomUUID, and next/server is Edge-native — so there is no Node-only import anywhere below this file. Do not add one.

Properties​

optional cookie?: AnonymousIdCookieConfig

Defined in: identity-adapter-nextjs/src/middleware.ts:19

Cookie settings; must match the settings given to <IdentityProvider>.

IdentityMiddlewareResult​

Defined in: identity-adapter-nextjs/src/middleware.ts:22

Properties​

anonymousId​

anonymousId: AnonymousId

Defined in: identity-adapter-nextjs/src/middleware.ts:31

created​

created: boolean

Defined in: identity-adapter-nextjs/src/middleware.ts:35

True when no usable cookie was present and a new id was generated.

response​

response: NextResponse

Defined in: identity-adapter-nextjs/src/middleware.ts:30

A NextResponse.next() that (a) carries the Set-Cookie header for the anonymous id and (b) forwards the id onto THIS request, so Server Components rendered by this very request already see it. Add your own headers to it, or ignore it and use setCookieHeader on a response you build yourself.

setCookieHeader​

setCookieHeader: string

Defined in: identity-adapter-nextjs/src/middleware.ts:33

Raw Set-Cookie value, for when you return your own Response.

Type Aliases​

AnonymousId​

AnonymousId = string & object

Defined in: identity-core/build/esm/index.d.ts:6

Canonical anonymous id. Branded so it can't be silently mixed up with a plain userId string at call sites.

Type Declaration​

__brand​

readonly __brand: "AnonymousId"

Functions​

applyAnonymousIdCookie()​

applyAnonymousIdCookie(response, setCookieHeader): Response

Defined in: identity-core/build/esm/index.d.ts:181

Convenience: append the Set-Cookie header onto an outgoing Response.

Parameters​

response​

Response

setCookieHeader​

string

Returns​

Response

identityMiddleware()​

identityMiddleware(config?): (request) => NextResponse

Defined in: identity-adapter-nextjs/src/middleware.ts:84

Ready-to-use middleware for apps with no middleware logic of their own:

// app's middleware.ts
export const middleware = identityMiddleware()
export const config = { matcher: ['/((?!_next/static|_next/image).*)'] }

Apps that already have middleware logic should use withIdentity.

Parameters​

config?​

IdentityMiddlewareConfig = {}

Returns​

(request) => NextResponse

withIdentity()​

withIdentity(request, config?): IdentityMiddlewareResult

Defined in: identity-adapter-nextjs/src/middleware.ts:52

Composition primitive — call this FIRST inside your own middleware.ts.

It is deliberately not a wrapper that takes your handler: apps commonly need to branch (redirect, rewrite, 401) and a wrapper forces every branch through one shape. Returning the pieces instead lets the app own control flow while still getting the cookie guarantee on every path.

The request.cookies.set() call is the load-bearing part on a cold load: without it the freshly generated id only exists on the response, so the Server Components rendering this same request would see no cookie and the first paint would disagree with the second. This is the direct fix for the "server can't see the id until the 2nd page load" problem in the plan.

Parameters​

request​

NextRequest

config?​

IdentityMiddlewareConfig = {}

Returns​

IdentityMiddlewareResult