feat: Next.js SSR Improvements #877

bcbogdan · 2025-02-04T09:30:30Z

Summary of change

The following PR improves SSR support in Next.js applications.
To get the session data in the context of server side rendering you now have to call getSSRSession either inside a Server Component, or in getServerSideProps (for older next applications).
There's two parts to this change:

Fetching the session during SSR

The logic for this is kept in the ssr.ts file. The function reads the active tokens and has 3 possible outcomes:

redirect to the login page if there was an issue (unable to read the tokens, token payload was invalid)
redirect to the refresh api if the tokens have expired or if the front token payload is different from the access token payload
return the session value

Refreshing a session

The getSSRSession function redirects to a refresh endpoint that we do not expose from our existing API.
Hence, this change adds logic inside the next.js middleware to handle such a request. The custom middleware calls the backend API using a fetch and updates the response with the new tokens.

This part is now kept mostly in the middleware.ts file, in the react library. It's there just to make it easy to review during this stage. It should be moved in the node SDK package as a separate, Nextjs specific API.

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)

Documentation changes

(If relevant, please create a PR in our docs repo, or create a checklist here highlighting the necessary changes)

Checklist for important updates

Remaining TODOs for this PR

Item1
Item2

github-actions · 2025-02-12T10:45:42Z

size-limit report 📦

Path	Size
lib/build/index.js	24.58 KB (+0.25% 🔺)
recipe/session/index.js	25.29 KB (+0.31% 🔺)
recipe/session/prebuiltui.js	30 KB (+0.2% 🔺)
recipe/thirdparty/index.js	32.37 KB (+0.19% 🔺)
recipe/emailpassword/index.js	11.74 KB (+0.68% 🔺)
recipe/emailverification/index.js	8.03 KB (+0.67% 🔺)
recipe/passwordless/index.js	15.64 KB (+0.55% 🔺)
recipe/emailverification/prebuiltui.js	34.73 KB (+0.37% 🔺)
recipe/thirdparty/prebuiltui.js	53.91 KB (+0.25% 🔺)
recipe/emailpassword/prebuiltui.js	40.91 KB (+0.3% 🔺)
recipe/passwordless/prebuiltui.js	128.89 KB (+0.12% 🔺)
recipe/multitenancy/index.js	6.9 KB (+1.05% 🔺)
recipe/multifactorauth/index.js	11.68 KB (+0.72% 🔺)
recipe/multifactorauth/prebuiltui.js	33.7 KB (+0.36% 🔺)
recipe/oauth2provider/index.js	7.65 KB (+0.74% 🔺)
recipe/oauth2provider/prebuiltui.js	32.07 KB (+0.29% 🔺)

porcellus · 2025-02-26T20:25:01Z

lib/ts/nextjs/ssr.ts

+    // TODO: This method is isolated atm to make it easier to test and debug
+    // In the end it should be merged in the getSSRSession function


Why do we need to merge it into getSSRSession? At first glance this works well as both the usecase and the impl is different enough.

porcellus · 2025-02-26T20:25:30Z

lib/ts/nextjs/ssr.ts

+        const redirectTo = "/";
+
+        const authPagePath = `${getAuthPagePath()}`;
+        const refreshLocation = `/api/auth/session/refresh?redirectTo=${redirectTo}`;


getRefreshLocation?

porcellus · 2025-02-26T20:27:06Z

lib/ts/nextjs/ssr.ts

+// TODO:
+// - Do we need to check the token version and handle ERR_JWKS_MULTIPLE_MATCHING_KEYS like in the node SDK?


I don't think we do, that only comes up with really old tokens IIRC

porcellus · 2025-02-26T20:27:39Z

lib/ts/nextjs/ssr.ts

+): Promise<{ isValid: true; payload: AccessTokenPayload["up"] } | { isValid: false }> {
+    const appInfo = SuperTokensNextjsSSRAPIWrapper.getConfigOrThrow().appInfo;
+    const jwksUrl = new URL(`${appInfo.apiBasePath}/jwt/jwks.json`, appInfo.apiDomain);
+    const JWKS = jose.createRemoteJWKSet(jwksUrl);


This should be cached/moved into a global location.

porcellus · 2025-02-26T20:31:43Z

lib/ts/nextjs/middleware.ts

+            logDebugMessage("Missing tokens from refresh response");
+            return redirectToAuthPage(request);
+        }
+        const redirectUrl = new URL(redirectTo, request.url);


Do we check if redirectTo is relative?

porcellus · 2025-02-26T20:45:13Z

lib/ts/nextjs/middleware.ts

+    // getSetCookie was added in node 18 and our build target is ES5
+    // This should not a problem here since the function runs in the Vercel edge runtime environment
+    // @ts-expect-error TS(2339): Property 'getSetCookie' does not exist on type 'Headers'.


As a TODO: let's review if we could raise our build-target

porcellus · 2025-02-26T20:48:32Z

lib/ts/recipe/session/utils.ts

@@ -113,3 +113,5 @@ export function validateAndCompareOnFailureRedirectionURLToCurrent(redirectURL:

    return currentUrl === fullRedirectURL;
 }
+
+export function getSessionForSSR() {}


I think this can be removed.

porcellus · 2025-02-26T20:48:42Z

lib/ts/recipe/session/types.ts

@@ -75,3 +75,28 @@ export type AccessDeniedThemeProps = {
 export type ComponentOverrideMap = {
    SessionAccessDenied_Override?: ComponentOverride<typeof AccessDeniedScreenTheme>;
 };
+
+export type AccessTokenPayload = {


I think this can be removed.

porcellus · 2025-02-26T20:49:11Z

lib/ts/recipe/session/ssr.ts

@@ -0,0 +1,154 @@
+import * as jose from "jose";


I think this can be removed.

porcellus · 2025-02-26T20:50:32Z

lib/ts/scratch.ts

@@ -0,0 +1,205 @@
+import * as jose from "jose";


You might want to remove this or move it into the with-typescript folder (that's what we use to "test" typings in ci/scripts as well as a scratch file)

porcellus · 2025-02-26T20:53:59Z

examples/with-next-ssr-app-directory/app/components/home.tsx

+     * SessionAuthForNextJS will handle proper redirection for the user based on the different session states.
+     * It will redirect to the login page if the session does not exist etc.


I'd say it handles redirections on the client side.

bcbogdan added 3 commits February 3, 2025 15:00

Add the base get session logic

57fbfc0

Update the function and add types

a7594c1

Add more info about the proposal

e278f9f

bcbogdan force-pushed the feat/nextjs-ssr branch from 944a484 to e278f9f Compare February 4, 2025 09:36

bcbogdan added 8 commits February 10, 2025 23:15

Account for pages directory in the function implementation

d99eea4

Update types and clean things up

9796608

Add comments

f4d8d50

Add nextjs init function

0109153

Add the jose library

45467c2

Fix refreshing and add example

88981c9

Fix build and token config

4613363

Fix payload processing

da4e86d

bcbogdan force-pushed the feat/nextjs-ssr branch from f2af627 to b306f85 Compare February 12, 2025 21:57

Load config fron env variables

ad89bbe

bcbogdan force-pushed the feat/nextjs-ssr branch from b306f85 to ad89bbe Compare February 12, 2025 21:57

bcbogdan added 8 commits February 14, 2025 11:07

Add a redirect location during refresh

08f9ca7

Refresh token from middleware

4190020

Move everything in the library

1d48378

Rename files and update function singatures

465f8d4

Use the correct refresh path

01e1533

Use normal responses instead of nextresponse

ea95af2

Use normal request instead of nextrequest

d366c32

Cleanup implementation

46f93b1

bcbogdan changed the title ~~Next.js SSR Improvements~~ feat: Next.js SSR Improvements Feb 24, 2025

bcbogdan force-pushed the feat/nextjs-ssr branch from 110ee20 to 8231792 Compare February 24, 2025 13:24

Revoke session inside the middleware

7c23d35

bcbogdan force-pushed the feat/nextjs-ssr branch from 8231792 to 7c23d35 Compare February 24, 2025 14:26

bcbogdan requested a review from porcellus February 24, 2025 14:42

porcellus requested changes Feb 26, 2025

View reviewed changes

porcellus reviewed Feb 26, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Next.js SSR Improvements #877

feat: Next.js SSR Improvements #877

bcbogdan commented Feb 4, 2025 •

edited

Loading

github-actions bot commented Feb 12, 2025 •

edited

Loading

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

porcellus Feb 26, 2025

		// TODO: This method is isolated atm to make it easier to test and debug
		// In the end it should be merged in the getSSRSession function

		// TODO:
		// - Do we need to check the token version and handle ERR_JWKS_MULTIPLE_MATCHING_KEYS like in the node SDK?

		* SessionAuthForNextJS will handle proper redirection for the user based on the different session states.
		* It will redirect to the login page if the session does not exist etc.

feat: Next.js SSR Improvements #877

Are you sure you want to change the base?

feat: Next.js SSR Improvements #877

Conversation

bcbogdan commented Feb 4, 2025 • edited Loading

Summary of change

Fetching the session during SSR

Refreshing a session

Test Plan

Documentation changes

Checklist for important updates

Remaining TODOs for this PR

github-actions bot commented Feb 12, 2025 • edited Loading

size-limit report 📦

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bcbogdan commented Feb 4, 2025 •

edited

Loading

github-actions bot commented Feb 12, 2025 •

edited

Loading