allow configuring session storage on callback route

[nicknisi]

Note

This is a port of the same functionality from authkit-remix.

This PR addresses issue #63 where users deploying to serverless environments (like AWS Lambda) experience errors in the callback route during cold starts. The error occurs because the session storage configuration happens in the root loader, but during cold starts the callback route might be hit first, resulting in:

Error: SessionStorage was never configured. Did you forget to call
configureSessionStorage in your root loader?

Changes

• Updated the authLoader function to accept the same storage and cookie configuration options that authkitLoader already supports
• Modified HandleAuthOptions type to support these new configuration options
• Changed the implementation to use configureSessionStorage directly in the callback route

How It Works

When a cold start happens in a serverless environment, the callback route can now configure session storage itself through the same interface already available in authkitLoader. This allows developers to provide consistent session storage configuration to both routes, ensuring the application works correctly regardless of which route is hit first.

Usage

For applications deployed to serverless environments, you can now use this pattern:

// Create a shared configuration function
function getAuthStorage() {
  return {
    storage: createCookieSessionStorage({...}),
    cookie: { name: "my-session" }
  };
}

// In your root loader
export const loader = (args) => authkitLoader(args, {
  ...getAuthStorage(),
  // Other options...
});

// In your callback route
export const loader = authLoader({
  ...getAuthStorage(),
  // Other options...
});

This ensures consistent session configuration across routes and prevents cold start errors.

README changes

This PR also adds a section describing sessoion storage configuration to the README, and notes the important case to configure in both laoders (when custom session storage is used).

[Copilot]

Pull Request Overview

This PR adds support for passing custom session storage and cookie settings to the callback route (authLoader) to prevent cold-start errors in serverless environments, and documents the new options.

• Extend HandleAuthOptions to require or forbid storage/cookie together.
• Update authLoader to call configureSessionStorage directly using provided storage/cookie.
• Add a README section on customizing session storage and advice for serverless deployments.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/interfaces.ts	Changed HandleAuthOptions from an interface to a discriminated union supporting optional custom storage and cookie settings
src/authkit-callback-route.ts	Swapped getSessionStorage for configureSessionStorage, destructured storage and cookie, and derived cookieName
README.md	Added "Customizing Session Storage" guide with examples and a serverless note

Comments suppressed due to low confidence (4)

src/interfaces.ts:6

• [nitpick] The type name HandleAuthOptions is somewhat generic; consider renaming it to AuthLoaderOptions to more clearly indicate it configures the authLoader function.

export type HandleAuthOptions = {

src/authkit-callback-route.ts:12

• Add unit tests for the new storage/cookie code path in authLoader to verify that configureSessionStorage is called and sessions behave correctly when custom storage is provided.

const { getSession, commitSession } = await configureSessionStorage({ storage, cookieName });

README.md:324

• Clarify that the cookie option only overrides the name for the default cookie-based storage; when supplying a custom SessionStorage, other cookie properties are ignored by configureSessionStorage.

  cookie: { name: "auth-session" }

src/interfaces.ts:6

• Ensure that SessionStorage and SessionIdStorageStrategy are imported at the top of this file; otherwise these types will be undefined and cause a compile error.

export type HandleAuthOptions = {

[MattyBalaam]

It would be good if this was released soon so we can complete our migration from remix to react router. 🙏 🥺

[stacurry]

@MattyBalaam we just released v0.5.0 which includes these changes.