Skip to content

Add decorateUrl to navigate callbacks for Safari ITP support#3037

Open
nikosdouvlis wants to merge 1 commit intocore-3from
nikos/user4475-udpate-docs-with-decorateurl
Open

Add decorateUrl to navigate callbacks for Safari ITP support#3037
nikosdouvlis wants to merge 1 commit intocore-3from
nikos/user4475-udpate-docs-with-decorateurl

Conversation

@nikosdouvlis
Copy link
Member

Summary

Updates all custom flow documentation to include the new decorateUrl function in navigate callbacks, enabling Safari ITP cookie refresh support.

  • Updated 25 documentation files with the decorateUrl pattern
  • Covers all authentication custom flows (current and legacy)
  • Includes Expo partial files

Why

Safari's Intelligent Tracking Prevention (ITP) limits cookies set via API responses from CNAME-cloaked subdomains to 7 days. This causes unexpected session expiration for Safari users who don't visit frequently. The decorateUrl function wraps destination URLs and may return an absolute URL when cookie refresh is needed.

The Pattern

All navigate callbacks now use:

navigate: async ({ session, decorateUrl }) => {
  const url = decorateUrl('/')
  if (url.startsWith('http')) {
    window.location.href = url
  } else {
    router.push(url)
  }
}

Related

Test plan

🤖 Generated with Claude Code

Why:
Safari's Intelligent Tracking Prevention (ITP) limits cookies set via API
responses from CNAME-cloaked subdomains to 7 days. This causes unexpected
session expiration for Safari users who don't visit frequently. The new
decorateUrl function in setActive/finalize navigate callbacks enables
automatic cookie refresh when needed.

What changed:
- Updated 25 doc files with decorateUrl pattern in navigate callbacks
- Pattern wraps destination URLs and checks if result is absolute (http)
  to determine whether to use window.location.href or router.push()
- Covers all custom flows: auth, legacy auth, Expo partials
- Skipped billing checkout finalize() - different API, not affected

Files: oauth-connections, sign-in-or-up, email-password, email-password-mfa,
email-sms-otp, passkeys, enterprise-connections, legal-acceptance,
embedded-email-links, multi-session-applications, session-tasks,
error-handling, forgot-password, application-invitations, expo partials
@nikosdouvlis nikosdouvlis requested a review from a team as a code owner February 4, 2026 11:27
@vercel
Copy link

vercel bot commented Feb 4, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview Feb 4, 2026 11:29am

Request Review

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants