feat: Next.js SSR Improvements (#877)

* improv: add an improved way of refreshing the session during SSR

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

* check server actions

* Add authenticate HOF for server actions

:q

* Update examples

* Code review fixes

* fix: Fix token management during ssr in header based setups

* test: Add nextjs e2e tests

* test: Extend e2e tests

* fix: Linting fixes

* chore: Update changelog

* fix: Move jwtVerify to a separate file and remove jose

* fix: Fix prune errors

* ci: Update core docker image

* chore: Remove comments

* fix: Fix exports to make tests work

* test: Update CI testing

* fix: Code review fixes

* fix: Use the correct path for the refresh token cookie

* fix: Update naming to underline lack of claim validation

* fix: Include requireAuth in the getServerActionSession function

* test: Fix flaky tests

* fix: Fix function names

* fix: review fixes

* chore: update size limit

---------

Co-authored-by: Mihaly Lengyel <[email protected]>

Author: bcbogdan

CHANGELOG.md

@@ -5,7 +5,9 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
-## [unreleased]
+## [0.51]
+
+-   Add utilities for session management during server side rendering
 
 ## [0.50] - 2025-08-15
 

compose.yml

@@ -1,7 +1,7 @@
 services:
     core:
         # Uses `$SUPERTOKENS_CORE_VERSION` when available, else latest
-        image: supertokens/supertokens-core:dev-branch-${SUPERTOKENS_CORE_VERSION:-master}
+        image: supertokens/supertokens-dev-postgresql:${SUPERTOKENS_CORE_VERSION:-master}
         ports:
             # Uses `$SUPERTOKENS_CORE_PORT` when available, else 3567 for local port
             - ${SUPERTOKENS_CORE_PORT:-3567}:3567

examples/for-tests-nextjs/.env

@@ -0,0 +1,5 @@
+EXT_PUBLIC_SUPERTOKENS_APP_NAME=test
+NEXT_PUBLIC_SUPERTOKENS_API_DOMAIN=http://localhost:3031
+NEXT_PUBLIC_SUPERTOKENS_WEBSITE_DOMAIN=http://localhost:3031
+NEXT_PUBLIC_SUPERTOKENS_API_BASE_PATH=/api/auth
+NEXT_PUBLIC_SUPERTOKENS_WEBSITE_BASE_PATH=/auth

examples/for-tests-nextjs/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+    "extends": "next/core-web-vitals"
+}

examples/for-tests-nextjs/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# VSCode
+.vscode

examples/for-tests-nextjs/README.md

@@ -0,0 +1,42 @@
+# SuperTokens App with Next.js app directory
+
+This is a simple application that is protected by SuperTokens. This app uses the Next.js app directory.
+
+## How to use
+
+### Using `create-next-app`
+
+-   Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example with-supertokens with-supertokens-app
+```
+
+```bash
+yarn create next-app --example with-supertokens with-supertokens-app
+```
+
+```bash
+pnpm create next-app --example with-supertokens with-supertokens-app
+```
+
+-   Run `yarn install`
+
+-   Run `npm run dev` to start the application on `http://localhost:3000`.
+
+### Using `create-supertokens-app`
+
+-   Run the following command
+
+```bash
+npx create-supertokens-app@latest --frontend=next
+```
+
+-   Select the option to use the app directory
+
+Follow the instructions after `create-supertokens-app` has finished
+
+## Notes
+
+-   To know more about how this app works and to learn how to customise it based on your use cases refer to the [SuperTokens Documentation](https://supertokens.com/docs/guides)
+-   We have provided development OAuth keys for the various built-in third party providers in the `/app/config/backend.ts` file. Feel free to use them for development purposes, but **please create your own keys for production use**.

examples/for-tests-nextjs/app/actions/protectedAction.ts

@@ -0,0 +1,18 @@
+"use server";
+
+import { cookies } from "next/headers";
+import { getServerActionSessionWithoutClaimValidation, init } from "supertokens-auth-react/nextjs/ssr";
+import { ssrConfig } from "../config/ssr";
+
+init(ssrConfig());
+
+export async function protectedAction() {
+    const cookiesStore = await cookies();
+    const { status, session } = await getServerActionSessionWithoutClaimValidation(cookiesStore);
+
+    if (status !== "valid") {
+        return { status, userId: undefined };
+    }
+
+    return { status, userId: session.userId };
+}

examples/for-tests-nextjs/app/actions/unprotectedAction.ts

@@ -0,0 +1,8 @@
+"use server";
+
+import { cookies } from "next/headers";
+import { ssrConfig } from "../config/ssr";
+
+export async function unprotectedAction() {
+    return Promise.resolve("success");
+}

examples/for-tests-nextjs/app/api/auth/[...path]/route.ts

@@ -0,0 +1,38 @@
+import { getAppDirRequestHandler } from "supertokens-node/nextjs";
+import Session, { refreshSessionWithoutRequestResponse } from "supertokens-node/recipe/session";
+import { NextRequest, NextResponse } from "next/server";
+import { ensureSuperTokensInit } from "../../../config/backend";
+import { cookies } from "next/headers";
+
+ensureSuperTokensInit();
+
+const handleCall = getAppDirRequestHandler();
+
+export async function GET(request: NextRequest) {
+    const res = await handleCall(request);
+    if (!res.headers.has("Cache-Control")) {
+        // This is needed for production deployments with Vercel
+        res.headers.set("Cache-Control", "no-cache, no-store, max-age=0, must-revalidate");
+    }
+    return res;
+}
+
+export async function POST(request: NextRequest) {
+    return handleCall(request);
+}
+
+export async function DELETE(request: NextRequest) {
+    return handleCall(request);
+}
+
+export async function PUT(request: NextRequest) {
+    return handleCall(request);
+}
+
+export async function PATCH(request: NextRequest) {
+    return handleCall(request);
+}
+
+export async function HEAD(request: NextRequest) {
+    return handleCall(request);
+}

examples/for-tests-nextjs/app/api/update-core/route.ts

@@ -0,0 +1,18 @@
+import { getCoreUrl } from "@/app/config/backend";
+import { NextResponse, NextRequest } from "next/server";
+import { withSession } from "supertokens-node/nextjs";
+
+export async function POST(request: NextRequest) {
+    const updatePayload: Record<string, unknown> = {};
+    const coreUrl = getCoreUrl();
+
+    await fetch(`${coreUrl}/recipe/multitenancy/connectionuridomain/v2`, {
+        method: "PUT",
+        body: JSON.stringify(updatePayload),
+        headers: {
+            "Content-Type": "application/json",
+        },
+    });
+
+    return NextResponse.json({});
+}