feat: adds cookies.encode option allowing minimal cookie sizes (#126)

Adds an experimental option `encode` on the `cookies` object when using
`createBrowserClient()` and `createServerClient()`.

If this is set to `tokens-only` then only the user's access token and
refresh token will be encoded in the cookies, causing significant cookie
size savings, often greater than 50%. It utilizes [split session storage
in `auth-js`](supabase/supabase-js#1545), with
some trade-offs such as the inability to access the `user` property on
the `supabase.auth.getSession()` object in the server. This wasn't
supposed to be done anyway, and `getClaims()` is a secure alternative
for it.

Author: hf

package-lock.json

@@ -33,7 +33,7 @@
   "homepage": "https://github.com/supabase/ssr#readme",
   "devDependencies": {
     "@eslint/js": "^9.3.0",
-    "@supabase/supabase-js": "^2.43.4",
+    "@supabase/supabase-js": "^2.57.4",
     "@types/node": "^24.3.0",
     "@vitest/coverage-v8": "^1.6.0",
     "eslint": "^8.57.0",

package.json

@@ -141,6 +141,13 @@ export function createBrowserClient<
       detectSessionInUrl: isBrowser(),
       persistSession: true,
       storage,
+      ...(options?.cookies &&
+      "encode" in options.cookies &&
+      options.cookies.encode === "tokens-only"
+        ? {
+            userStorage: options?.auth?.userStorage ?? window.localStorage,
+          }
+        : null),
     },
   });
 

src/createBrowserClient.ts

@@ -12,6 +12,7 @@ import type {
   CookieMethodsServer,
   CookieMethodsServerDeprecated,
 } from "./types";
+import { memoryLocalStorageAdapter } from "./utils/helpers";
 
 /**
  * @deprecated Please specify `getAll` and `setAll` cookie methods instead of
@@ -170,6 +171,14 @@ export function createServerClient<
       detectSessionInUrl: false,
       persistSession: true,
       storage,
+      ...(options?.cookies &&
+      "encode" in options.cookies &&
+      options.cookies.encode === "tokens-only"
+        ? {
+            userStorage:
+              options?.auth?.userStorage ?? memoryLocalStorageAdapter(),
+          }
+        : null),
     },
   });
 

src/createServerClient.ts

@@ -33,6 +33,15 @@ export type CookieMethodsBrowserDeprecated = {
 };
 
 export type CookieMethodsBrowser = {
+  /**
+   * If set to true, only the user's session (access and refresh tokens) will be encoded in cookies. The user object will be encoded in local storage if the `userStorage` option is not provided when creating the client.
+   *
+   * You should keep this option the same between `createBrowserClient()` and `createServerClient()`. When set to `tokens-only` accessing the `user` property on the data returned from `getSession()` will only be possible if the user has already been stored in the separate storage. It's best to use `getClaims()` instead to avoid surprizes.
+   *
+   * @experimental
+   */
+  encode?: "user-and-tokens" | "tokens-only";
+
   getAll: GetAllCookies;
   setAll: SetAllCookies;
 };
@@ -44,6 +53,15 @@ export type CookieMethodsServerDeprecated = {
 };
 
 export type CookieMethodsServer = {
+  /**
+   * If set to `tokens-only`, only the user's access and refresh tokens will be encoded in cookies. The user object will be encoded in memory if the `userStorage` option is not provided when creating the client. Unset value defaults to `user-and-tokens`.
+   *
+   * You should keep this option the same between `createBrowserClient()` and `createServerClient()`. When set to `tokens-only` accessing the `user` property on the data returned from `getSession()` will not be possible. Use `getUser()` or preferably `getClaims()` instead.
+   *
+   * @experimental
+   */
+  encode?: "user-and-tokens" | "tokens-only";
+
   getAll: GetAllCookies;
   setAll?: SetAllCookies;
 };

src/types.ts

@@ -51,3 +51,25 @@ export function isBrowser() {
     typeof window !== "undefined" && typeof window.document !== "undefined"
   );
 }
+
+/**
+ * Returns a localStorage-like object that stores the key-value pairs in
+ * memory.
+ */
+export function memoryLocalStorageAdapter(
+  store: { [key: string]: string } = {},
+) {
+  return {
+    getItem: (key: string) => {
+      return store[key] || null;
+    },
+
+    setItem: (key: string, value: string) => {
+      store[key] = value;
+    },
+
+    removeItem: (key: string) => {
+      delete store[key];
+    },
+  };
+}