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% 🔺)

lib/ts/nextjs/ssr.ts

lib/ts/nextjs/middleware.ts

lib/ts/recipe/session/utils.ts

lib/ts/recipe/session/types.ts

lib/ts/recipe/session/ssr.ts

lib/ts/scratch.ts

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

Update the function and add types Add more info about the proposal Account for pages directory in the function implementation Update types and clean things up Add comments Add nextjs init function Add the jose library Fix refreshing and add example Fix build and token config Fix payload processing Load config fron env variables Add a redirect location during refresh Refresh token from middleware Move everything in the library Rename files and update function singatures Use the correct refresh path Use normal responses instead of nextresponse Use normal request instead of nextrequest Cleanup implementation Revoke session inside the middleware Code review fixes Add tests for getSSRSession Add tests for middleware

:q

lib/ts/nextjs/constants.ts

lib/ts/nextjs/middleware.ts

lib/ts/nextjs/constants.ts

lib/ts/nextjs/middleware.ts

package.json

porcellus · 2025-05-12T20:50:20Z

lib/ts/nextjs/ssr.ts

+        accessTokenPayload,
+        doesSessionExist: true,
+        loading: false,
+        invalidClaims: [],


We should somehow communicate that this doesn't do claim validation, but maybe docs are enough.

porcellus · 2025-05-12T20:51:18Z

lib/ts/nextjs/ssr.ts

+    cookies: CookiesObject | CookiesStore
+): Promise<{ state: SSRSessionState; session?: LoadedSessionContext }> {
+    const frontToken =
+        getCookieValue(cookies, FRONT_TOKEN_COOKIE_NAME) || getCookieValue(cookies, FRONT_TOKEN_HEADER_NAME);


FRONT_TOKEN_HEADER_NAME doesn't appear as a cookie I think.

lib/ts/nextjs/ssr.ts

lib/ts/nextjs/middleware.ts

porcellus · 2025-05-26T10:01:06Z

lib/ts/nextjs/middleware.ts

+function defaultIsApiRequest(request: Request): boolean {
+    const requestUrl = new URL(request.url);
+    const refreshPath = getRefreshAPIPath();
+    return requestUrl.pathname.startsWith(refreshPath);
+}


I think this isn't right, or the name is misleading.

porcellus · 2025-05-26T10:06:03Z

lib/ts/nextjs/ssr.ts

     * @returns The server action return value
     **/
-    static async authenticateServerAction<T extends (session: LoadedSessionContext) => Promise<K>, K>(action: T) {
-        let loadedSessionContext: LoadedSessionContext | undefined = undefined;
+    static async confirmAuthenticationAndCallServerAction<T extends () => Promise<K>, K>(action: T) {


I think a shorter name would be better.

Suggested change

static async confirmAuthenticationAndCallServerAction<T extends () => Promise<K>, K>(action: T) {

static async ensureSessionAndCall<T extends () => Promise<K>, K>(action: T) {

porcellus · 2025-05-26T10:20:28Z

lib/ts/nextjs/ssr.ts

+function getRefreshAPIPath(): string {
+    const apiPath = SuperTokensNextjsSSRAPIWrapper.getConfigOrThrow().appInfo.apiBasePath || DEFAULT_API_PATH;
+    return `${apiPath}/session/refresh`;
+}
+
 function getRefreshLocation(redirectPath: string): string {
-    return `${SESSION_REFRESH_API_PATH}?${REDIRECT_PATH_PARAM_NAME}=${redirectPath}`;
+    const refreshAPIPath = getRefreshAPIPath();
+    return `${refreshAPIPath}?${REDIRECT_PATH_PARAM_NAME}=${redirectPath}`;
 }


I think the first name is also present in the middleware file, you could indicate in the name that one path is meant for the frontend/as a full page redirect.

porcellus · 2025-05-26T10:27:00Z

lib/ts/utils.ts

+        throw new Error("JWT header missing alg (Algorithm)");
+    }
+
+    const jwksResponse = await fetch(jwksUrl);


This will reload the jwks on every action call, could we cache this somehow? Also, I'm not necessarily opposed to using jose if it doesn't mess with our bundle sizes.

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

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

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

bcbogdan force-pushed the feat/nextjs-ssr branch 2 times, most recently 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

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

bcbogdan force-pushed the feat/nextjs-ssr branch 6 times, most recently from ebadbed to 3f9b519 Compare March 4, 2025 10:49

bcbogdan force-pushed the feat/nextjs-ssr branch from 3f9b519 to 0797deb Compare March 4, 2025 19:25

bcbogdan force-pushed the feat/nextjs-ssr branch from 578dc07 to 22365e9 Compare March 18, 2025 09:07

check server actions

5bfbbd1

bcbogdan force-pushed the feat/nextjs-ssr branch from 22365e9 to 5bfbbd1 Compare March 18, 2025 09:12

Add authenticate HOF for server actions

3b1973c

:q

bcbogdan force-pushed the feat/nextjs-ssr branch from db16f4e to 3b1973c Compare May 5, 2025 07:52

Update examples

0c1ecca

bcbogdan force-pushed the feat/nextjs-ssr branch from ff038f8 to 0c1ecca Compare May 7, 2025 07:58

bcbogdan requested a review from porcellus May 7, 2025 08:01

porcellus requested changes May 12, 2025

View reviewed changes

bcbogdan force-pushed the feat/nextjs-ssr branch from d5e6c65 to 6ca5ce6 Compare May 20, 2025 18:17

Code review fixes

deccb9c

bcbogdan force-pushed the feat/nextjs-ssr branch from 6ca5ce6 to deccb9c Compare May 21, 2025 08:47

bcbogdan force-pushed the feat/nextjs-ssr branch from 1bee927 to 85aefe5 Compare May 21, 2025 09:02

Merge branch 'master' into feat/nextjs-ssr

f781088

bcbogdan force-pushed the feat/nextjs-ssr branch from 85aefe5 to f781088 Compare May 21, 2025 09:09

porcellus requested changes May 26, 2025

View reviewed changes

	static async confirmAuthenticationAndCallServerAction<T extends () => Promise<K>, K>(action: T) {
	static async ensureSessionAndCall<T extends () => Promise<K>, K>(action: T) {

feat: Next.js SSR Improvements #877

Are you sure you want to change the base?

feat: Next.js SSR Improvements #877

Uh oh!

Conversation

bcbogdan commented Feb 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of change

Fetching the session during SSR

Refreshing a session

Test Plan

Documentation changes

Checklist for important updates

Remaining TODOs for this PR

Uh oh!

github-actions bot commented Feb 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

porcellus May 12, 2025

Choose a reason for hiding this comment

Uh oh!

porcellus May 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

porcellus May 26, 2025

Choose a reason for hiding this comment

Uh oh!

porcellus May 26, 2025

Choose a reason for hiding this comment

Uh oh!

porcellus May 26, 2025

Choose a reason for hiding this comment

Uh oh!

porcellus May 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bcbogdan commented Feb 4, 2025 •

edited

Loading

github-actions bot commented Feb 12, 2025 •

edited

Loading