Skip to main content

Session Management

Session management in Archibald is a coordinated effort between the client-side SessionClient and the server-side AuthModule. It is designed to be isomorphic, ensuring authentication state is consistent across both environments.

The SessionClient​

The SessionClient is the central orchestrator on the client-side. It is responsible for:

  • Storing the current authentication state.
  • Coordinating with Authentication Adapters for token storage.
  • Triggering automatic token refreshes in the background.

Bootstrapping​

The session system must be provided to the React application via the SessionClientProvider. In Archibald, it is idiomatic to use the ProviderComposer in your main App component to handle this setup.

import { SessionClientProvider } from '@archibald/auth';
import { ProviderComposer, provider } from '@archibald/core';
import sessionClient from './api/creators/session';

function App() {
    return (
        <ProviderComposer
            providers={[
                provider(SessionClientProvider, { client: sessionClient }),
                // ... other core providers
            ]}
        >
            <AppLayout />
        </ProviderComposer>
    );
}

Accessing Session Data​

Developers primarily interact with the session through a set of React Hooks. These hooks provide a reactive interface to the user's data and login status:

  • useUser: The standard way to retrieve the current user profile.
  • useIsLoggedIn: A lightweight boolean check for authentication state.
  • useLogin / useLogOut: Mutation hooks to handle session lifecycle events.

Server-Side Context​

On the server, you can access the session data within services or controllers without a request object by using the getSession() function. This is powered by the ServerContext and ensures that user identity is available deep within your business logic.