Custom Storage

This guide shows how to pick a storage for session data and how to plug in your own implementation.

What you'll cover

Use the built-in LocalStorage, SessionStorage, or MemoryStorage
Implement a custom storage
Separate sessions for multiple clients on the same origin

Before you begin

This guide assumes you've completed the JavaScript quickstart or the installation guide.

You should already have:

A Single Page App configured in MonoCloud
The @monocloud/auth-web-js SDK installed
A MonoCloudWebJSClient initialized

Built-in storage

By default the SDK stores the session in LocalStorage so it survives page reloads and new tabs. Three implementations ship with the SDK:

Storage	Persistence	When to use it
`LocalStorage`	Until the user signs-out	Default. Shared across tabs and persists across reloads
`SessionStorage`	The tab is open	When the session should end when the tab is closed
`MemoryStorage`	The page is loaded	Tests, ephemeral previews, or when running inside an iframe with no storage

Pick the storage at construction time:

src/auth.ts

import {
  MonoCloudWebJSClient,
  SessionStorage,
} from "@monocloud/auth-web-js";

export const client = new MonoCloudWebJSClient({
  tenantDomain: "https://<your-domain>",
  clientId: "<your-client-id>",
  storage: new SessionStorage(),
});

Implement a custom storage

Provide your own storage by implementing the IStorage interface. Anything that can asynchronously read, write, and delete string keys works - cookies, IndexedDB wrappers, native bridges, and so on.

src/auth.ts

import {
  type IStorage,
  MonoCloudWebJSClient,
} from "@monocloud/auth-web-js";

class CookieStorage implements IStorage {
  async getItem(key: string): Promise<string | null> {
    const match = document.cookie
      .split("; ")
      .find((row) => row.startsWith(`${key}=`));
    return match
      ? decodeURIComponent(match.slice(key.length + 1)) || null
      : null;
  }

  async setItem(key: string, value: string): Promise<void> {
    document.cookie = `${key}=${encodeURIComponent(value)}; path=/; secure; samesite=strict`;
  }

  async removeItem(key: string): Promise<void> {
    document.cookie = `${key}=; path=/; max-age=0`;
  }
}

export const client = new MonoCloudWebJSClient({
  tenantDomain: "https://<your-domain>",
  clientId: "<your-client-id>",
  storage: new CookieStorage(),
});

Things to keep in mind:

All three methods are async - return Promise<string | null> and Promise<void>
The SDK serializes session values as strings, so the storage only needs to handle strings

Separate sessions for multiple clients on the same origin

If you run two MonoCloudWebJSClient instances against the same clientId on the same origin (for example, two micro-frontends), set sessionKey so the storage keys don't collide:

src/auth.ts

import { MonoCloudWebJSClient } from "@monocloud/auth-web-js";

export const adminClient = new MonoCloudWebJSClient({
  tenantDomain: "https://<your-domain>",
  clientId: "<your-client-id>",
  sessionKey: "admin",
});

export const portalClient = new MonoCloudWebJSClient({
  tenantDomain: "https://<your-domain>",
  clientId: "<your-client-id>",
  sessionKey: "portal",
});

Each client now reads and writes its own session bucket.

Custom Storage

What you'll cover

Before you begin

Built-in storage

Implement a custom storage

Separate sessions for multiple clients on the same origin

Next steps