Supabase SSR

https://github.com/supabase/ssr
Admin
Supabase clients for use in SSR frameworks, providing a framework-agnostic way to create a Supabase...
Tokens:53,564
Snippets:276
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### memoryLocalStorageAdapter() usage

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/utils.md

Usage example for memoryLocalStorageAdapter. Creates an in-memory store, demonstrates setItem/getItem/removeItem, and shows sharing an existing map.

```ts
import { memoryLocalStorageAdapter } from "@supabase/ssr";

const store = memoryLocalStorageAdapter();
store.setItem("user", '{"name":"Ada"}');
store.getItem("user"); // '{"name":"Ada"}'
store.removeItem("user");
store.getItem("user"); // null
// an existing map can be shared:
const shared = memoryLocalStorageAdapter({ "k": "v" });
```

--------------------------------

### Error handling example

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/clearAuthCookiesAtScopes.md

Shows how to handle errors thrown by the helper, which only throws if the provided getAll/setAll functions throw.

```ts
try {
  await clearAuthCookiesAtScopes({ getAll, setAll, storageKey, scopes });
} catch (error) {
  // propagate or log — e.g. getAll threw because no Cookie header was present
  logger.error("failed to clear legacy auth cookies", error);
}
```

--------------------------------

### Install @supabase/ssr with npm, pnpm, yarn, or bun

Source: https://github.com/supabase/ssr/blob/main/README.md

Install the @supabase/ssr package using your preferred package manager. The package replaces the deprecated @supabase/auth-helpers-* packages.

```bash
npm i @supabase/ssr
```

```bash
pnpm add @supabase/ssr
```

```bash
yarn add @supabase/ssr
```

```bash
bun add @supabase/ssr
```

--------------------------------

### createBrowserClient - Missing setAll Cookie Method (get only)

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when options.cookies provides only a get method (deprecated path) and a write operation is required. The error indicates that getAll and setAll (or get, set, remove) must be configured.

```APIDOC
## createBrowserClient - Missing setAll Cookie Method (get only)

### Description
Thrown when `options.cookies` provides only a `get` method (deprecated path) and a write operation is required. The error indicates that `getAll` and `setAll` (or alternatively `get`, `set`, `remove`) must be configured.

### Trigger
`options.cookies` provides `get` only; writing would be required but cannot be performed.

### Error Message
```
@supabase/ssr: createBrowserClient requires configuring a getAll and setAll cookie method (deprecated: alternatively both get, set and remove can be used)
```
```

--------------------------------

### Domain migration example

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/clearAuthCookiesAtScopes.md

Clears auth cookies for a domain migration from .foo.com to .bar.com. Uses the storage key 'sb-<project-ref>-auth-token' and scope { domain: ".foo.com" }.

```ts
import { clearAuthCookiesAtScopes } from "@supabase/ssr";

await clearAuthCookiesAtScopes({
  getAll,
  setAll,
  storageKey: "sb-<project-ref>-auth-token",
  scopes: [{ domain: ".foo.com" }],
});
```

--------------------------------

### Error handling for createServerClient

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createServerClient.md

Shows the two main error conditions: empty supabaseUrl or supabaseKey throws 'Your project's URL and Key are required to create a Supabase client! ...', and passing an empty cookies object throws an error from src/cookies.ts:220 because neither get nor getAll is present.

```ts
import { createServerClient } from "@supabase/ssr";

try {
  createServerClient("", "");
} catch (error) {
  // "Your project's URL and Key are required to create a Supabase client! ..."
  console.error(error.message);
}

try {
  createServerClient(url, key, { cookies: {} });
} catch (error) {
  // Error from src/cookies.ts:220 (neither get nor getAll present)
  console.error(error.message);
}
```

--------------------------------

### Path migration example

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/clearAuthCookiesAtScopes.md

Clears auth cookies for a path migration from /app to /. Uses the storage key 'sb-<project-ref>-auth-token' and scope { path: "/app" }.

```ts
import { clearAuthCookiesAtScopes } from "@supabase/ssr";

await clearAuthCookiesAtScopes({
  getAll,
  setAll,
  storageKey: "sb-<project-ref>-auth-token",
  scopes: [{ path: "/app" }],
});
```

--------------------------------

### createServerClient - No Cookie Accessors

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when options.cookies is omitted or empty on the server, as there is no document.cookie to fall back to. The error indicates that getAll and setAll (or get, set, remove) must be specified.

```APIDOC
## createServerClient - No Cookie Accessors

### Description
Thrown when `options.cookies` is omitted or empty on the server, as there is no `document.cookie` to fall back to. The error indicates that `getAll` and `setAll` (or `get`, `set`, `remove`) must be specified.

### Trigger
`options.cookies` omitted or empty on the server.

### Error Message
```
@supabase/ssr: createServerClient must be initialized with cookie options that specify getAll and setAll functions (deprecated, not recommended: alternatively use get, set and remove)
```
```

--------------------------------

### createClient - No Cookie Accessors at All

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when options.cookies is an object without get or getAll accessors, in either client. The error message varies by runtime (browser vs server).

```APIDOC
## createClient - No Cookie Accessors at All

### Description
Thrown when `options.cookies` is an object without `get` or `getAll` accessors, in either client. The error message varies by runtime (browser vs server).

### Trigger
`options.cookies` is an object without `get` and without `getAll` (e.g. `{}`, or `{ encode: "tokens-only" }` in a configuration the compiler rejects).

### Error Message (Server)
```
@supabase/ssr: createServerClient requires configuring getAll and setAll cookie methods (deprecated: alternatively use get, set and remove).
```

### Error Message (Browser)
```
@supabase/ssr: createServerClient requires configuring getAll and setAll cookie methods (deprecated: alternatively use get, set and remove). As this is called in a browser runtime, consider removing the cookies option object to use the document.cookie API automatically.
```
```

--------------------------------

### Cookie chunking state change example

Source: https://github.com/supabase/ssr/blob/main/docs/design.md

Illustrates the cookie chunking state change from non-chunked to chunked. The first object shows the incoming cookies, the second shows the desired new state, and the HTTP commands show the required Set-Cookie headers, including clearing stale cookies.

```typescript
{
   'storage-item': 'value',
   'storage-item.0': 'value',
   'storage-item.1': 'value',
   'storage-item.5': 'value',
}
```

```typescript
{
   'storage-item.0': 'val',
   'storage-item.1': 'ue',
}
```

```http
Set-Cookie: storage-item.0=val; Max-Age=<many seconds>
Set-Cookie: storage-item.1=ue;  Max-Age=<many seconds>
Set-Cookie: storage-item=;   Max-Age=0
Set-Cookie: storage-item.5=; Max-Age=0
```

--------------------------------

### createBrowserClient - Non-Browser Runtime Without Cookie Accessors

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when createBrowserClient is called outside a browser (e.g., Next.js pre-rendering) with no cookie accessors, and an auth operation needs to write state. The error indicates that getAll and setAll (or get, set, remove) must be specified.

```APIDOC
## createBrowserClient - Non-Browser Runtime Without Cookie Accessors

### Description
Thrown when `createBrowserClient` is called outside a browser (e.g., Next.js pre-rendering) with no cookie accessors, and an auth operation needs to write state. The error indicates that `getAll` and `setAll` (or `get`, `set`, `remove`) must be specified.

### Trigger
`createBrowserClient` called outside a browser with no `cookies` accessors, and an auth operation needs to write state.

### Error Message
```
@supabase/ssr: createBrowserClient in non-browser runtimes (including Next.js pre-rendering mode) was not initialized cookie options that specify getAll and setAll functions (deprecated: alternatively use get, set and remove), but they were needed
```
```

--------------------------------

### createBrowserClient Overload 2 (deprecated get/set/remove)

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createBrowserClient.md

Deprecated overload that accepts `get`, `set`, and `remove` cookie methods. These methods will not be supported in the next major version; use `getAll` and `setAll` instead.

```ts
/**
 * @deprecated Please specify `getAll` and `setAll` cookie methods instead of
 * the `get`, `set` and `remove`. These will not be supported in the next major
 * version.
 */
export function createBrowserClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options?: SupabaseClientOptions<SchemaName> & {
    cookies: CookieMethodsBrowserDeprecated;
    cookieOptions?: CookieOptionsWithName;
    cookieEncoding?: "raw" | "base64url";
    isSingleton?: boolean;
  },
): SupabaseClient<Database, SchemaName>;
```

--------------------------------

### parseCookieHeader() usage

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/utils.md

Usage example for parseCookieHeader. Pass the Cookie header value (or an empty string) to get an array of cookie name/value pairs.

```ts
import { parseCookieHeader } from "@supabase/ssr";

const cookiesForGetAll = parseCookieHeader(
  request.headers.get("Cookie") ?? "",
); // e.g. [{ name: "sb-auth-token", value: "base64-…" }]
```

--------------------------------

### createServerClient(url, key, options)

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createServerClient.md

Creates a Supabase client with a server storage adapter for cookie-based authentication. Returns a SupabaseClient instance with an internal onAuthStateChange subscription and applies storage changes via setAll.

```APIDOC
## createServerClient(url, key, options)

### Description
Creates a Supabase client configured for server-side usage with cookie-based authentication. The client uses a server storage adapter flagged `isServer: true` and registers an internal `onAuthStateChange` subscription. Storage changes are applied via `setAll` when pending and the event is one of: `SIGNED_IN`, `TOKEN_REFRESHED`, `USER_UPDATED`, `PASSWORD_RECOVERY`, `SIGNED_OUT`, `MFA_CHALLENGE_VERIFIED`.

### Return Type
`SupabaseClient<Database, SchemaName>` — a `@supabase/supabase-js` client with a server storage adapter flagged `isServer: true`.

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
- **supabaseUrl** (string) - Required - The project URL.
- **supabaseKey** (string) - Required - The project API key.
- **options** (object) - Required - Configuration object.
  - **cookies** (object) - Required - Cookie accessor object.
    - **getAll** (function) - Required (unless using get/set/remove) - Function to read all cookies.
    - **setAll** (function) - Required (unless using get/set/remove) - Function to write all cookies.
    - **get** (function) - Optional - Function to read a single cookie (deprecated alternative).
    - **set** (function) - Optional - Function to write a single cookie (deprecated alternative).
    - **remove** (function) - Optional - Function to remove a single cookie (deprecated alternative).

### Request Example
```ts
import { createServerClient, parseCookieHeader } from "@supabase/ssr";

const supabase = createServerClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_PUBLISHABLE_KEY!,
  {
    cookies: {
      getAll() {
        return parseCookieHeader(request.headers.get("Cookie") ?? "");
      },
      setAll(cookiesToSet, headers) {
        // store cookies and headers for later response
      },
    },
  },
);
```

### Response
#### Success Response (200)
- **client** (SupabaseClient) - The created Supabase client.

#### Response Example
```ts
const supabase = createServerClient(url, key, { cookies: { getAll, setAll } });
```

### Error Handling
| Error | Condition | Source |
|---|---|---|
| `Error` — `Your project's URL and Key are required to create a Supabase client! …` | `supabaseUrl` or `supabaseKey` is empty/falsy | `src/createServerClient.ts:135` |
| `Error` — `createServerClient must be initialized with cookie options that specify getAll and setAll functions (deprecated, not recommended: alternatively use get, set and remove)` | no `cookies` accessors at all supplied to `options.cookies` | `src/cookies.ts:229` |
| `Error` — needs both `getAll` and `setAll` (or `get`+`set`+`remove`) | a `cookies` object with a partial accessor set was passed | `src/cookies.ts:220` |
```

--------------------------------

### createBrowserClient()

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createBrowserClient.md

Documentation for the createBrowserClient function, including its overloads, parameters, and return type.

```APIDOC
## createBrowserClient()

### Description
Creates a Supabase Client configured for **browser** runtimes. The session is always persisted in cookies (never local storage) so a server-rendered request can read it.

### Import
`import { createBrowserClient } from "@supabase/ssr";`

### Source
`src/createBrowserClient.ts`

### Overloads

#### Overload 1 — recommended (custom cookie accessors)

Signature copied verbatim from `src/createBrowserClient.ts:47`:

```ts
export function createBrowserClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options?: SupabaseClientOptions<SchemaName> & {
    cookies?: CookieMethodsBrowser;
    cookieOptions?: CookieOptionsWithName;
    cookieEncoding?: "raw" | "base64url";
    isSingleton?: boolean;
  },
): SupabaseClient<Database, SchemaName>;
```

#### Overload 2 — deprecated (`get`/`set`/`remove`)

Signature copied verbatim from `src/createBrowserClient.ts:69`:

```ts
/**
 * @deprecated Please specify `getAll` and `setAll` cookie methods instead of
 * the `get`, `set` and `remove`. These will not be supported in the next major
 * version.
 */
export function createBrowserClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options?: SupabaseClientOptions<SchemaName> & {
    cookies: CookieMethodsBrowserDeprecated;
    cookieOptions?: CookieOptionsWithName;
    cookieEncoding?: "raw" | "base64url";
    isSingleton?: boolean;
  },
): SupabaseClient<Database, SchemaName>;
```

### Implementation (what the compiler resolves to)

`src/createBrowserClient.ts:86` — third (implementation) signature with `cookies?: CookieMethodsBrowser | CookieMethodsBrowserDeprecated;`. The two overloads above are the only publicly visible ones; the implementation signature is not callable directly.

### Parameters

- **supabaseUrl** (string) - Required - The URL of the Supabase project.
- **supabaseKey** (string) - Required - The API key for the Supabase project.
- **options** (SupabaseClientOptions<SchemaName> & { cookies?: CookieMethodsBrowser; cookieOptions?: CookieOptionsWithName; cookieEncoding?: "raw" | "base64url"; isSingleton?: boolean; }) - Optional - Configuration options for the client.

### Returns

- **SupabaseClient<Database, SchemaName>** - A Supabase client instance configured for browser runtimes.
```

--------------------------------

### Multiple scopes example

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/clearAuthCookiesAtScopes.md

Clears auth cookies for multiple scopes at once, e.g., domain and path combinations. Shows usage with requestCookieReader and responseCookieWriter.

```ts
import { clearAuthCookiesAtScopes } from "@supabase/ssr";

await clearAuthCookiesAtScopes({
  getAll: requestCookieReader, // e.g. () => parseCookieHeader(req.headers.get("Cookie") ?? "")
  setAll: responseCookieWriter, // e.g. Next.js cookies().setAll
  storageKey: "sb-abc123-auth-token",
  scopes: [{ domain: ".foo.com" }, { domain: ".bar.com", path: "/app" }],
});
```

--------------------------------

### createBrowserClient - Missing setAll Cookie Method (getAll only)

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when options.cookies provides only a getAll method and a setAll is required for a custom store. The error indicates that both getAll and setAll must be configured.

```APIDOC
## createBrowserClient - Missing setAll Cookie Method (getAll only)

### Description
Thrown when `options.cookies` provides only a `getAll` method and a `setAll` is required for a custom store. The error indicates that both `getAll` and `setAll` must be configured.

### Trigger
`options.cookies` provides `getAll` only; a `setAll` is required for a custom store.

### Error Message
```
@supabase/ssr: createBrowserClient requires configuring both getAll and setAll cookie methods (deprecated: alternatively both get, set and remove can be used)
```
```

--------------------------------

### serializeCookieHeader() usage in response middleware

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/utils.md

Usage example for serializeCookieHeader in response middleware. Appends a Set-Cookie header with the given options, using CookieOptions type.

```ts
import { serializeCookieHeader } from "@supabase/ssr";
import type { CookieOptions } from "@supabase/ssr";

response.headers.append(
  "Set-Cookie",
  serializeCookieHeader(name, value, {
    path: "/",
    sameSite: "lax",
    httpOnly: false,
    maxAge: 400 * 24 * 60 * 60,
  } satisfies CookieOptions),
);
```

--------------------------------

### createBrowserClient

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createBrowserClient.md

Documentation for the createBrowserClient function, including its parameters, defaults, and behavior.

```APIDOC
## createBrowserClient

### Description
Creates a Supabase client for use in browser environments, configured to persist the session via cookies. It accepts the project URL and anon key, plus options for cookie handling, authentication behavior, and more.

### Method
Function call

### Signature
`createBrowserClient<Database, SchemaName>(supabaseUrl: string, supabaseKey: string, options?: BrowserOptions<SchemaName>): SupabaseClient<Database, SchemaName>`

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `supabaseUrl` | `string` | yes | — | The URL of the Supabase project. |
| `supabaseKey` | `string` | yes | — | The `anon` API key of the Supabase project. |
| `options.cookies` | `CookieMethodsBrowser` (`getAll` + `setAll`) or deprecated `CookieMethodsBrowserDeprecated` (`get` + `set` + `remove`), or omitted | no | omitted — falls back to `document.cookie` in browser runtimes | Custom cookie store accessors. `getAll`/`setAll` must be provided together, or (deprecated) `get`, `set` and `remove` must all be provided. See [types.md](../types.md) for shapes. |
| `options.cookieOptions` | `CookieOptionsWithName` | no | `undefined` → each cookie is written with `DEFAULT_COOKIE_OPTIONS` (`path: "/", sameSite: "lax", httpOnly: false, maxAge: 400 days`); `name` maps to `auth.storageKey` | Options applied to every cookie write, plus optional `name` used as the auth storage key. |
| `options.cookieEncoding` | `"raw" \| "base64url"` | no | `"base64url"` | How cookie values are encoded; `base64url` prefixes values with `base64-`. |
| `options.isSingleton` | `boolean` | no | `true` in browsers when the option is omitted; `false` if explicitly set to `false` or when running outside a browser | Whether the created client is cached and reused for subsequent calls in the same process. |
| `options.auth.flowType` | (from `SupabaseClientOptions`) | no | forced to `"pkce"` (source overrides the option) | Ignored/overridden — the client always uses the PKCE flow. |
| `options.auth.autoRefreshToken` | `boolean` | no | `isBrowser()` result (i.e. `true` in browsers) | Access-token auto refresh on expiry. An explicit value is respected. |
| `options.auth.detectSessionInUrl` | `boolean` | no | `isBrowser()` result (i.e. `true` in browsers) | Whether to detect session data in the URL hash on page load. An explicit value is respected. |
| `options.auth.persistSession` | `boolean` | no | `true` | Whether the session is persisted to the storage adapter. An explicit value is respected. |
| `options.auth.storage` | (storage adapter, from `SupabaseClientOptions`) | no | **ignored** | **Always ignored** — documented in the source: "The `auth.storage` option is ignored. The session is always persisted via cookies." Passing it logs a one-time console warning. |
| `options.auth.userStorage` | (storage adapter, from `SupabaseClientOptions`) | no | `window.localStorage` in browsers, else `memoryLocalStorageAdapter()` | Used **only** when `options.cookies.encode === "tokens-only"`; stores the user object. |
| `options.cookies.encode` | `"user-and-tokens" \| "tokens-only"` | no | `"user-and-tokens"` (unset) | `"tokens-only"` persists only access/refresh tokens in cookies and routes the user object to `userStorage`. @experimental |
| `options.global.headers` | (from `SupabaseClientOptions`) | no | library adds `"X-Client-Info": "supabase-ssr/<VERSION> createBrowserClient"` | Merged into outgoing request headers. |

All other `SupabaseClientOptions<SchemaName>` fields (e.g. `db`, `global.fetch`, `auth.autoRefreshToken`, `auth.signInWithOtp`, `auth.emailRedirectTo`, `auth.captchaToken`, …) are passed through to `@supabase/supabase-js`'s `createClient`.

`Database`/`SchemaName` are generic type parameters mapping to the generated database types; `SchemaName` resolves to `"public"` by default when `public` exists in the database type, otherwise any schema key.

### Return Value
Returns a `SupabaseClient` instance configured for browser use with cookie-based session persistence.

### Notes
- The `auth.storage` option is always ignored; the session is always persisted via cookies.
- The `auth.flowType` option is overridden to `"pkce"`.
- The `options.cookies.encode` option is experimental.
- The `options.isSingleton` option caches the client for reuse in the same process when `true` (default in browsers).
```

--------------------------------

### CookieMethodsServerDeprecated

Source: https://github.com/supabase/ssr/blob/main/_autodocs/types.md

Deprecated type for server cookie methods. Accepted by createServerClient overload 2. Includes get, set, and remove methods, with set and remove optional.

```APIDOC
## CookieMethodsServerDeprecated

### Description
Deprecated type for server cookie methods. Accepted by createServerClient overload 2. Includes get, set, and remove methods, with set and remove optional.

### Type Definition
```ts
export type CookieMethodsServerDeprecated = {
  get: GetCookie;
  set?: SetCookie;
  remove?: RemoveCookie;
};
```

### Fields
- **get** (GetCookie) - Required - Read one cookie.
- **set** (SetCookie) - Optional - Write one cookie.
- **remove** (RemoveCookie) - Optional - Remove one cookie.

### Deprecation
Deprecated. Accepted by createServerClient overload 2. set/remove are optional — omitting them yields a warning-on-write setAll.
```

--------------------------------

### Overload 2 - deprecated get/set/remove signature

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createServerClient.md

Deprecated overload using get, set, and remove cookie methods. Marked for removal in the next major version.

```typescript
/**
 * @deprecated Please specify `getAll` and `setAll` cookie methods instead of
 * the `get`, `set` and `remove`. These will not be supported in the next major
 * version.
 */
export function createServerClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options: SupabaseClientOptions<SchemaName> & {
    cookieOptions?: CookieOptionsWithName;
    cookies: CookieMethodsServerDeprecated;
    cookieEncoding?: "raw" | "base64url";
  },
): SupabaseClient<Database, SchemaName>;
```

--------------------------------

### createServerClient - Missing Project URL/API Key

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when supabaseUrl or supabaseKey is empty or falsy when creating a server client. The error message instructs the user to check their Supabase project's API settings.

```APIDOC
## createServerClient - Missing Project URL/API Key

### Description
Thrown when `supabaseUrl` or `supabaseKey` is empty/falsy during server client creation. The error message instructs the user to check their Supabase project's API settings.

### Trigger
`supabaseUrl` or `supabaseKey` is empty/falsy.

### Error Message
```
Your project's URL and Key are required to create a Supabase client!

Check your Supabase project's API settings to find these values

https://supabase.com/dashboard/project/_/settings/api
```
```

--------------------------------

### CookieMethodsBrowserDeprecated Type Definition

Source: https://github.com/supabase/ssr/blob/main/_autodocs/types.md

Defines the deprecated cookie methods structure accepted by createBrowserClient overload 2. All three methods (get, set, remove) must be provided.

```ts
export type CookieMethodsBrowserDeprecated = {
  get: GetCookie;
  set: SetCookie;
  remove: RemoveCookie;
};
```

--------------------------------

### createStorageFromOptions()

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/cookies.md

Documentation for the createStorageFromOptions function, including its signature, parameters, return value, and behavior notes.

```APIDOC
## createStorageFromOptions()

### Description
Creates a storage object for use with `@supabase/supabase-js`'s `createClient`, handling cookie encoding, chunking, and browser/server write semantics.

### Signature
```ts
export function createStorageFromOptions(
  options: {
    cookieEncoding: "raw" | "base64url";
    cookies?:
      | CookieMethodsBrowser
      | CookieMethodsBrowserDeprecated
      | CookieMethodsServer
      | CookieMethodsServerDeprecated;
    cookieOptions?: CookieOptionsWithName;
  },
  isServerClient: boolean,
)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `options.cookieEncoding` | `"raw" \| "base64url"` | yes | — | `"base64url"` prefixes every written value with `base64-` before Base64-URL-encoding. |
| `options.cookies` | one of the four `CookieMethods*` shapes, or omitted | no | `null`-equivalent | An object carrying only `encode` (no accessors) is treated the same as omitting it. |
| `options.cookieOptions` | `CookieOptionsWithName` | no | `undefined` | Merged into every cookie written (with `maxAge` overridden: `0` for removals, `DEFAULT_COOKIE_OPTIONS.maxAge` for sets); the `name` field is deleted before writing so the Next.js cookie store does not get confused. |
| `isServerClient` | `boolean` | no | — | `true` from `createServerClient`, `false` from `createBrowserClient`. Selects buffered vs. immediate write semantics. |

### Return Value
Returns an object with `getAll`, `setAll`, `setItems`, `removedItems`, and a `storage` object. The `storage` object is passed as `auth.storage` to `@supabase/supabase-js`'s `createClient`.

**Browser storage (`isServerClient = false`):**
```ts
{
  getAll: (keyHints: string[]) => ReturnType<GetAllCookies>,
  setAll: SetAllCookies,
  setItems: { [key: string]: string },
  removedItems: { [key: string]: boolean },
  storage: {
    isServer: false,
    getItem: async (key: string) => Promise<string | null>,
    setItem: async (key: string, value: string) => Promise<void>,
    removeItem: async (key: string) => Promise<void>,
  }
}
```

**Server storage (`isServerClient = true`):**
```ts
{
  getAll: (keyHints: string[]) => ReturnType<GetAllCookies>,
  setAll: SetAllCookies,
  setItems: { [key: string]: string },
  removedItems: { [key: string]: boolean },
  storage: {
    isServer: true,
    getItem: async (key: string) => Promise<string | null>,
    setItem: async (key: string, value: string) => Promise<void>,
    removeItem: async (key: string) => Promise<void>,
  }
}
```

### Behavior Notes
- **Browser storage**: `getItem` reads via `getAll([key])` and `combineChunks`; `setItem` reads existing cookies, clears every chunk-like name (`key`, `key.N`) that will be replaced (including a host-only variant when `cookieOptions.domain` is set, and a domain-scoped variant), then writes new chunks via `setAll`. `removeItem` clears all chunk-like names (host-only first, then domain-scoped) using `maxAge: 0`.
- **Server storage**: `getItem` first checks the buffered `setItems` map, then `removedItems`, then reads cookies. `setItem` writes to `setItems` (and deletes the `removedItems` entry); `removeItem` writes to `removedItems` (and deletes the `setItems` entry).
- **PKCE code-verifier special cases** (server storage):
  - `setItem` on any key ending in `-code-verifier` immediately calls `applyServerStorage` (pretending only that key was set) because no auth event announces verifier writes.
  - `removeItem` on a key matching `isPkceVerifierSlotKey` or `isPkceFlowIndexKey` immediately calls `applyServerStorage` (pretending only that key was removed) because those keys can be removed on event-less paths (ring eviction at flow start, or flow failure). Plain `-code-verifier` removals are left buffered since an event (or overwrite) always follows.
- **Header thinning (server)**: the returned `setAll` wraps the caller's `setAll`; the cache-prevention `headers` argument is forwarded only on the **first** call that carries non-empty headers, then `hasSentHeaders` suppresses it forever for that client.

### Accessor Resolution Matrix
| `cookies` given | isServerClient | Resolution |
|---|---|---|
| `get` only | — | `getAll` = fetch key plus first 5 chunk names (`key.0`…`key.5`) via `get` (deprecated path). If `set`+`remove` also given → `setAll` writes/clears each. If not: server → warning `setAll`; browser → **throws** (`src/cookies.ts:198`). |
| `getAll` (+ optional `setAll`) | — | `getAll` delegates. If `setAll` given → used directly. If not: server → warning `setAll`; browser → **throws** (`src/cookies.ts:214`). |
| object with neither `get` nor `getAll` (e.g. `{}` or `{ encode }`) | — | **throws** (`src/cookies.ts:220`). |
| omitted + browser runtime | `false` | `getAll`/`setAll` fall back to `document.cookie` (parsing via `cookie.parse`, writing via `cookie.serialize`). |
| omitted + not a browser | `false` | `getAll` returns `[]`; `setAll` **throws** when invoked (`src/cookies.ts:240`). |
| omitted | `true` | **throws** (`src/cookies.ts:229`). |
```

--------------------------------

### createBrowserClient

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createBrowserClient.md

Documentation for the createBrowserClient function, including return type, errors, warnings, and behavior notes.

```APIDOC
## createBrowserClient

### Description
Creates a Supabase client configured for browser environments with cookie-based authentication storage. Returns a fully configured `@supabase/supabase-js` client.

### Return Type
`SupabaseClient<Database, SchemaName>` — a fully configured `@supabase/supabase-js` client whose `auth.storage` is a cookie-backed storage adapter. All Supabase API methods (`auth`, `from`, `rpc`, `storage`, …) are available as documented by `@supabase/supabase-js`.

### Throws

| Error | Condition | Source |
|---|---|---|
| `Error` — `@supabase/ssr: Your project's URL and API key are required to create a Supabase client! …` | `supabaseUrl` or `supabaseKey` is empty/falsy | `src/createBrowserClient.ts:114` |
| `Error` — needs `getAll` + `setAll` (or deprecated `get` + `set` + `remove`) | a `cookies` object with only `get`, or only `getAll`, or neither was passed | `src/cookies.ts:198`, `src/cookies.ts:214`, `src/cookies.ts:220` |
| `Error` — cookie accessors were needed but not configured | `setAll` invoked by auth in a non-browser runtime (e.g. Next.js pre-rendering) without `getAll`/`setAll` configured | `src/cookies.ts:240` |

### Warnings
- Passing `options.auth.storage` logs a one-time warning.
- Using deprecated `get`/`set`/`remove` logs a deprecation warning at creation time if `setAll` ends up being needed.

### Behavior Notes
- A module-level `cachedBrowserClient` holds a singleton. `shouldUseSingleton` is `true` when `options.isSingleton === true`, **or** when no `isSingleton` key is present in `options` at all and `isBrowser()` returns `true`.
- The merged auth config order is: `options.auth` first, then `storageKey` (from `cookieOptions.name`), `flowType: "pkce"`, computed `autoRefreshToken`, `detectSessionInUrl`, `persistSession`, `storage`, and — only for `tokens-only` — `userStorage`. Later entries win.
```

--------------------------------

### createServerClient()

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createServerClient.md

Creates a Supabase Client for the server-side of an SSR framework. The session is read from request cookies, and storage changes are buffered and flushed to `setAll` on auth state changes.

```APIDOC
## createServerClient()

### Description
Creates a Supabase Client for the server-side of an SSR framework (middlewares, routes/APIs, server-rendered pages). The session is read from request cookies, and storage changes are buffered and flushed to `setAll` on auth state changes.

### Import
```ts
import { createServerClient } from "@supabase/ssr";
```

### Overload 1 — recommended (`getAll` + `setAll`)

#### Signature
```ts
export function createServerClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options: SupabaseClientOptions<SchemaName> & {
    cookieOptions?: CookieOptionsWithName;
    cookies: CookieMethodsServer;
    cookieEncoding?: "raw" | "base64url";
  },
): SupabaseClient<Database, SchemaName>;
```

#### Parameters
- **supabaseUrl** (string) - Required - The Supabase project URL.
- **supabaseKey** (string) - Required - The Supabase API key.
- **options** (object) - Required - Configuration object with the following properties:
  - **cookieOptions** (CookieOptionsWithName) - Optional - Cookie options.
  - **cookies** (CookieMethodsServer) - Required - Cookie methods for server-side session handling.
  - **cookieEncoding** ("raw" | "base64url") - Optional - Encoding for cookies.

#### Returns
- **SupabaseClient<Database, SchemaName>** - A Supabase client instance.

### Overload 2 — deprecated (`get`/`set`/`remove`)

#### Signature
```ts
/**
 * @deprecated Please specify `getAll` and `setAll` cookie methods instead of
 * the `get`, `set` and `remove`. These will not be supported in the next major
 * version.
 */
export function createServerClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options: SupabaseClientOptions<SchemaName> & {
    cookieOptions?: CookieOptionsWithName;
    cookies: CookieMethodsServerDeprecated;
    cookieEncoding?: "raw" | "base64url";
  },
): SupabaseClient<Database, SchemaName>;
```

#### Parameters
- **supabaseUrl** (string) - Required - The Supabase project URL.
- **supabaseKey** (string) - Required - The Supabase API key.
- **options** (object) - Required - Configuration object with the following properties:
  - **cookieOptions** (CookieOptionsWithName) - Optional - Cookie options.
  - **cookies** (CookieMethodsServerDeprecated) - Required - Deprecated cookie methods (`get`, `set`, `remove`).
  - **cookieEncoding** ("raw" | "base64url") - Optional - Encoding for cookies.

#### Returns
- **SupabaseClient<Database, SchemaName>** - A Supabase client instance.

### Implementation (what the compiler resolves to)
The implementation signature accepts `cookies: CookieMethodsServer | CookieMethodsServerDeprecated;`. Note the `options` object is **required** in all overloads (unlike `createBrowserClient`).
```

--------------------------------

### Error handling for misconfiguration

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createBrowserClient.md

Error handling for misconfiguration. Throws if URL or API key is missing, and throws immediately if only one of getAll/setAll is provided.

```ts
import { createBrowserClient } from "@supabase/ssr";

let supabase;
try {
  supabase = createBrowserClient("", "unknown-key"); // missing URL
} catch (error) {
  // Error: "@supabase/ssr: Your project's URL and API key are required to
  // create a Supabase client! ..."
  console.error(error.message);
}

// Passing only one of getAll/setAll also throws immediately:
try {
  createBrowserClient(url, key, {
    cookies: {
      getAll: () => [],
      // setAll missing -> Error from src/cookies.ts:214
    },
  });
} catch (error) {
  console.error(error.message);
}
```

--------------------------------

### Constraint summary (options.cookies)

Source: https://github.com/supabase/ssr/blob/main/_autodocs/types.md

Summary of constraints for the options.cookies parameter in createServerClient and createBrowserClient.

```APIDOC
## Constraint summary (options.cookies)

### Description
Summary of constraints for the options.cookies parameter in createServerClient and createBrowserClient.

### Constraints
- createServerClient requires options.cookies with at least getAll (or deprecated get).
- createBrowserClient accepts options.cookies optionally; omitting it entirely in a browser uses document.cookie.
- getAll/setAll must be provided together for a custom store; get+set+remove must be provided together on the deprecated path. Partial sets throw (see errors.md).
- A cookies object with only encode (no accessors) is treated identically to omitting it.
```

--------------------------------

### Catch missing URL/API key error from createBrowserClient

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Catches the error thrown when createBrowserClient is called with an empty supabaseUrl or supabaseKey. The error message starts with "@supabase/ssr: Your project's URL and API key…".

```ts
import { createBrowserClient } from "@supabase/ssr";

try {
  createBrowserClient("", "anon-key");
} catch (error) {
  console.error(error.message); // starts with "@supabase/ssr: Your project's URL and API key…"
}
```

--------------------------------

### createBrowserClient - Missing Project URL/API Key

Source: https://github.com/supabase/ssr/blob/main/_autodocs/errors.md

Thrown when supabaseUrl or supabaseKey is empty or falsy when creating a browser client. The error message instructs the user to check their Supabase project's API settings.

```APIDOC
## createBrowserClient - Missing Project URL/API Key

### Description
Thrown when `supabaseUrl` or `supabaseKey` is empty/falsy during browser client creation. The error message instructs the user to check their Supabase project's API settings.

### Trigger
`supabaseUrl` or `supabaseKey` is empty/falsy.

### Error Message
```
@supabase/ssr: Your project's URL and API key are required to create a Supabase client!

Check your Supabase project's API settings to find these values

https://supabase.com/dashboard/project/_/settings/api
```

### Catch Example
```ts
import { createBrowserClient } from "@supabase/ssr";

try {
  createBrowserClient("", "anon-key");
} catch (error) {
  console.error(error.message); // starts with "@supabase/ssr: Your project's URL and API key…"
}
```
```

--------------------------------

### Overload 1 - recommended getAll/setAll signature

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/createServerClient.md

Recommended overload using getAll and setAll cookie methods. The options object is required.

```typescript
export function createServerClient<
  Database = any,
  SchemaName extends string & keyof Omit<Database, "__InternalSupabase"> =
    "public" extends keyof Omit<Database, "__InternalSupabase">
      ? "public"
      : string & keyof Omit<Database, "__InternalSupabase">,
>(
  supabaseUrl: string,
  supabaseKey: string,
  options: SupabaseClientOptions<SchemaName> & {
    cookieOptions?: CookieOptionsWithName;
    cookies: CookieMethodsServer;
    cookieEncoding?: "raw" | "base64url";
  },
): SupabaseClient<Database, SchemaName>;
```

--------------------------------

### warnOnce(message)

Source: https://github.com/supabase/ssr/blob/main/_autodocs/api-reference/diagnostics.md

Logs a message via console.warn only once per process per distinct message.

```APIDOC
## warnOnce(message)

### Description
Logs a message via `console.warn` only once per process per distinct message. Used for configuration warnings that would otherwise fire on every client creation.

### Method
Function

### Signature
```ts
export function warnOnce(message: string): void
```

### Parameters
- **message** (string) - Required - The message to log.

### Behavior
- Deduplicates messages using an internal `Set<string>`.
- Logs only once per process per distinct message.

### Example
```ts
import { warnOnce } from "@supabase/ssr"; // internal — not exported from index

warnOnce("custom warning"); // logged
warnOnce("custom warning"); // not logged again
```

### Notes
- Not re-exported at the package root; import from `src/warnOnce.ts`.
- Triggered internally by `createBrowserClient` and `createServerClient` when passing `options.auth.storage`.
```
Tokens:
Raw