Next.js Routing and Redirects#

Overview#

Dify's web frontend uses Next.js App Router with a configurable basePath for sub-path deployments (e.g., running the UI at /dify instead of /). Routing behavior is centralized in next.config.ts, with authentication redirect flows handled by a dedicated server-side route handler.

Key Files#

basePath Configuration#

basePath is set in next.config.ts from env.NEXT_PUBLIC_BASE_PATH. This is the only build-time variable baked into the image at build (rather than injected at runtime) 1. Valid values must start with / and not end with / (e.g., /dify); the default is an empty string.

Auto-prepending behavior: When basePath is set in next.config.ts, Next.js automatically prepends it to all <Link> hrefs, router.push() calls, redirect() calls, and asset paths — neither client nor server code needs to manually add the prefix. This applies uniformly across client components, server components, and route handlers.

Application-level usage: The basePath export from web/utils/var.ts is used in limited cases where the base path must be computed or inspected directly. For example, auth/refresh/route.ts uses it to define the AUTH_REFRESH_PATH constant and to prepend it to signin redirect URLs constructed with NextResponse.redirect(). Server-side redirects triggered via next/navigation's redirect() function do not require manual prepending; Next.js handles basePath automatically.

Static Redirects#

next.config.ts defines a static redirect: /explore/apps → / (permanent, 308) 2

Frame protection (anti-clickjacking): Iframe embedding security is enforced at the application level by the Next.js proxy middleware (web/proxy.ts). The proxy sets X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on protected routes (including /device and console routes) while allowing published app routes (/chat, /workflow, /completion, /webapp-signin, /agent, /chatbot) to remain embeddable. See the "Iframe Embedding Security" documentation for details on the proxy's frame protection implementation.

Auth Refresh Redirect Flow#

The token refresh flow uses a dedicated Next.js Route Handler at GET /auth/refresh.

Trigger: CommonLayoutHydrationBoundary in the common layout RSC catches 401 API responses and calls redirectToAuthRefresh(), which redirects to /auth/refresh?redirect_url=<current-path> using next/navigation's redirect() function. Because basePath is configured in next.config.ts, Next.js automatically prepends it to the destination—no manual prepending is needed. The current path is read from x-dify-pathname and x-dify-search request headers injected by middleware 4.

Refresh handler logic (route.ts):

1. Extract and validate redirect_url from query params via resolveSafeRedirectTarget() 5
2. POSTs to the backend /refresh-token endpoint using the request's cookies 6
3. On success: returns HTTP 303 to the validated redirect_url, forwarding Set-Cookie headers from the backend 7
4. On failure (no cookie, no refresh URL, or non-OK response): returns HTTP 303 to ${basePath}/signin?redirect_url=<encoded-target>

redirect_url validation prevents open redirects and loops 9:

• Absolute same-origin URLs are not allowed (allowSameOriginAbsolute: false)
• Uses resolveLoginRedirectTarget() to classify the target as internal or absolute; if neither, falls back to the server login fallback
• Internal targets without basePath have it prepended via addBasePathToInternalTarget() 10
• Redirecting back to /auth/refresh itself is blocked (redirect loop prevention) 11

Relative redirect URLs: All Location headers are relative paths, not absolute URLs. This was introduced in PR #36847 to prevent leaking internal service hostnames in split-origin deployments (where the web frontend and API backend run on different hosts/ports).

Navigation Primitives#

web/next/navigation.ts is a thin re-export of next/navigation. All internal code should import navigation hooks (useRouter, usePathname, redirect, etc.) from @/next/navigation rather than directly from next/navigation. This provides a single indirection point if the import source ever needs to change.

Related PRs#